Administration Commands

Management of kissdx

* Since version 0.14 Administration of kissdx streaming media server is available through a command line utility which is kissdx itself.

Once your kissdx server is started and listens on an administration TCP port, as specified in its configuration file, you are able to control it remotely. Therefore, the utility may be run on the same host or from a remote host, with the same behavior.

The current administration commands allow you to stop your streaming server gracefuly (this avoids a CTRL C or kill command) and to manage the configuration (view, reload). The set of commands is growing with successive releases of kissdx.

This feature is based on TCP communications between the streaming server and the client utility. Make sure to allow data on this TCP port between those two hosts. Refer to the full description of kissdx network architecture for more details.

Synopsis overview of administration command

Here is an extract from the command line help screen:

KiSS PC-Link daemon v0.14 - Feb xx 2009 Usage: ./kissdx [media center options] | [admin options]

Note: Option sets 'Media' and 'Admin' are mutually exclusive. kissdx may be invoked as a server: Media center kissdx may be invoded as a client: Administration command

Media center options:

   -c,   --config FILE     Path to the configuration file
   -d,   --daemon          Fork into background and log using syslog
   -h,   --help            Print this on-line help
   -vn,  --verbose=n       Set logging level (1 to 5).  No level means 5.
                           The logging level can also be specified as one of:
                           Error, Warning, Protocol, Information or Debug

Administration options: -s COMMAND [-m HOST] [-p PORT]

   -s,   --send COMMAND    Invoke admin controller with COMMAND
   -m,   --mediacenter     Target name/IP to send command   (default: localhost)
   -p,   --port            TCP port to send admin command   (default: 8003)

Administration commands: -s COMMAND Refer verbose help for full command set explanation.

   -s   STOP               Stop kissdx mediacenter gracefully    (-s s)
   -s   FORCESTOP          Stop kissdx mediacenter immediately   (-s frs)
   -s   RELOAD_CONFIG      Reload configuration file             (-s rlc)
   -s   GET_TXT_CONFIG     Show currently loaded configuration   (-s gtc)

Samples:
   kissdx -vh            Verbose help including network TCP port usage
   kissdx -s STOP -v     Graceful stop (local run): Current streaming continues
   kissdx -s STOP -p 8003 -m media.home.fr

Some admin command to ease diagnostics: -s COMMAND

   -s lau                List audio  
   -s lpi                List picture
   -s lvi                List video  
   -s lvi /video/kids/   Commands could browse the mediacenter

Some admin command for developpers: -s Setter & Getter

   -s {verror;vwarn;vinfo;vproto;vdebug;v1..v5}   Set VerboseLogLevel  
   -s {slisthidden.yes;slisthidden.no;}     Set ListHiddenEntry          Yes/No  
   -s {scal.yes;scal.no;}                   Set ConfigAutoLoad           Yes/No  
   -s {sdsn.yes;sdsn.no;}                   Set DisplaySequenceNumber    Yes/No  

   -s {gksv;gksvd}            Get KissdxServerVersion; KissdxServerVersionDate
   -s {glarg;gldt}            Get launch command line arguments; launch date time
   -s {glcus}                 Get launch command line custom options (-x -y -z)
   -s {gdic}                  Retrieve dictionary of supported admin commands
   -s {gverbose;glisthidden}  Get VerboseLogLevel; ListHiddenEntry 
   -s {gcal;gdsn}             Get ConfigAutoLoad;  DisplaySequenceNumber

STOP - shortcut 's'

The STOP administration command tells kissdx streaming server:

• No new requests for media streaming should be accepted.
• Proceed with any current streaming to KiSS player until streaming ends.

When all current streaming has ended, kissdx streaming server stops running. The 'kissdx' process will terminate.

In order to restart kissdx, you should run a command line like ./kissdx -dc /etc/kissdx.conf

FORCESTOP - shortcut 'frs'

The FORCESTOP administration command tells kissdx streaming server:

       No new requests for media streaming should be accepted.
       Stop immediately any current streaming to KiSS players without waiting for them to end. 

When all current streaming has been stopped, kissdx streaming server stops running. The 'kissdx' process will terminate.

In order to restart kissdx, you should run a command line like ./kissdx -dc /etc/kissdx.conf

GET_TXT_CONFIG - shortcut 'gtc'

The GET_TXT_CONFIG administration command gets back a text oriented view of the configuration currently loaded in kissdx streaming server.

   Example of viewing configuration remotly:
   =============================================================
   Settings loaded in memory  
   kissdx version = v0.14 / Feb xx 2009
   Configuration file = /etc/kissdx.conf
   =============================================================
   audiopath = /mnt/unsecure/media4kissdx/audio
   audiopath = /media/cdrom0
   videopath = /mnt/unsecure/media4kissdx/video
   videopath = /mnt/unsecure/media4kissdx/video2
   videopath = /media/cdrom0
   picturepath = /mnt/unsecure/media4kissdx/picture
   picturepath = /media/cdrom0
   persistentstoragepath = 
   pidfilepath = /var/run/kissdx.pid
   ....

RELOAD_CONFIG - shortcut 'rlc'

The RELOAD_CONFIG administration command tells kissdx streaming server:

• Proceed with any current streaming to KiSS players as normal.
• Reload the configuration from the kissdx.conf file, and continue accepting new request for media streaming.

The settings for the running kissdx server are updated with your latest changes.

Note that multiple locations of the kissdx configuration file is supported. The search order is as follows (1 is read first, 4 is read last if not found in 1,2 or 3):

   1. location specified in command line argument: kissdx -c full-path-to-config-file
   2. ~/.kissdx (~/ means /home/{your_user}/ )
   3. ./kissdx.conf
   4. /etc/kissdx.conf 

Since the search will stop when the first kissdx configuration file found, a different file may be loaded than when kissdx was originally launched.

• Originally kissdx streaming server was launched with an existing /etc/kissdx.conf configuration file.
• A new ~/.kissdx configuration file is created.
• When the 'Reload_config' command is executed, the configuration is read from ~/.kissdx even if /etc/kissdx.conf still exists.

Note also that if the configuration file found has errors in it, it will be rejected and the current configuration is unchanged. A message appears on the console or in the syslog like the following. It explains that the original file /etc/kissdx.conf was correct and allowed kissdx to start the first time. But since, the configuration file has been changed and now has errors. A reminder of the original configuration location should help debugging.

   [ 8250] 2007-10-10 21:57:41 =============================================================
   [ 8250] 2007-10-10 21:57:41 ... Ready for streaming business
   [ 8250] 2007-10-10 21:57:41 Server signature : ubuntu.homeip.net-v0.13.x/2007-09-01 (OK)
   ....
   [ 8250] 2007-10-10 22:01:36 Received identity request from 10.39.10.5
   [ 8250] 2007-10-10 22:01:36 Reading configuration file '/etc/kissdx.conf'
   [ 8250] 2007-10-10 22:01:36 Unknown option in config file: jconfigautoload
   [ 8250] 2007-10-10 22:01:36 Error(s) in the configuration file prevent kissdx from using the file.
   [ 8250] 2007-10-10 22:01:36 Loading new config failed from   : /etc/kissdx.conf
   [ 8250] 2007-10-10 22:01:36 Keep previous configuration from : /etc/kissdx.conf
   [ 8250] 2007-10-10 22:01:36 =============================================================

In which case, the remote administration feature is so usefull ?

In this release of kissdx, the administration command are available through command line. A set of more "human friendly interfaces" are in cooking: See for exemple, the Win32 [kissdx Control center]

Avoid repetitive technical task via direct telnet connection

Imagine your kissdx streaming server running for months and your suddend need to stop this service. Forget the technical "killall kissdx" and mandatory telnet connection to your nas. Prefer a remote administration from your desktop computer and reduce any human error. This command avoid a "kicking them off".

   ./kissdx -s Stop -m MediaServerIP 
   ./kissdx -ss -m MediaServerIP (use 's' as a shortcut to 'Stop') 

Access the extrem stop command

Imagine your users are currently streaming media (video, audio, ...). You wish to stop the server and force current user streaming to be stopped. Using ForceStop command does not let any chance to start a new streaming and request immediate stop of kissdx master daemon and all the child internaly created.

   ./kissdx -s ForceStop -m MediaServerIP 
   ./kissdx -sfrs -m MediaServerIP (use 'frs' as a shortcut to 'Forcestop') 

Include a new media repository without stopping the streaming service to users

Imagine your service is online and many users streaming their favorite media. You had followed the recommandation to disable "automatic reloading configuration file on each pclink server research trigger by KiSS player". In this situation, you could modify the configuration file (kissdx.conf) without disturbing the streaming service because any modification of kissdx.conf will not be reloaded automaticaly. Test your configuration via ./kissdx -t MyconfigurationFile (to be done in future release). And finally request the running kissdx service to reload the configuration. Your user will access the new repositoty on their next request.

   ./kissdx -s ReloadConfig -m MediaServerIP 
   ./kissdx -srlc -m MediaServerIP (use 'rlc' as a shortcut to 'ReloadConfig') 

You have Forgot the original configuration used months ago while kissdx has be started

Imagine your service is started for months and you do not remember which configuration file has been used at this far far ago time startup. No need to telnet your nas, and find any configuration file to guess which one has been loaded in memory. Simply request kissdx server which one is currently loaded. Using GetTxtConfig you get access to the path of current kissdx.conf and all parameter:value couple.

   ./kissdx -s GetTxtConfig -m MediaServerIP 
   ./kissdx -sgtc -m MediaServerIP (use 'gtc' as a shortcut to 'GetTextConfig') 

You wish to know which media is streamed at the moment by kissdx

Imagine you need to know at the moment, the list of media streamed to all your KiSS players. Simply request kissdx which is the current status. (To be published in next release).

   ./kissdx -s Status -m MediaServerIP 
   ./kissdx -ssta -m MediaServerIP (use 'sta' as a shortcut to 'Status') 

You need to identify the version of a running kissdx without disturbing its streaming service

Owner of multiple NAS, you have setup kissdx on each of them. You wish to analyse the impact of upgrading to the last release. First thing is to identify which releases are currently in use in your environement without stopping streaming service of your customer or family user. Get each kissdx engine release detail using the remote command :

   ./kissdx -sgksv -m MediaServerIP (use 'gksv' to 'Get Kissdx Server Version') 
   ./kissdx -sgksvd -m MediaServerIP (use 'gksvd' to 'Get Kissdx Server Version Date') 

You wish to test a new configuration without modifying persistent configuration file (kissdx.conf)

This command enable you to change the configuration and behaviour loaded in memory without changing persistent configuration file kissdx.conf. it would be an appreciate feature in config testing approach.

   ./kissdx -sslisthidden.yes -m MediaServerIP (enable the options ListHiddenEntry to 'Yes') 
   ./kissdx -sslisthidden.no -m MediaServerIP (disable the options ListHiddenEntry to 'No') 
   ./kissdx -sscal.yes -m MediaServerIP (enable the options Configuration Auto Load) 
   ./kissdx -ssdsn.yes -m MediaServerIP (enable the options Display Sequence Number) 

Retrieved from "http://www.famille-kahn.com/kissdxmanual/Kissdx_user_manual:_Management"