m4/lls/server_cmd.suite.m4

   1 [suite server_cmd]
   2 caption = list of server commands
   3 aux_info_prefix = Permissions:
   4
   5 [introduction]
   6         The server process listens on a network socket and accepts connections
   7         from para_client or para_audiod. For the connection to succeed the
   8         connecting peer must authenticate as one of the users stored in the
   9         user table of para_server. Each entry of the user table contains the
  10         set of permission bits that are granted to the user. Authenticated
  11         users may execute one of the commands below if the set of permission
  12         bits of the command is a subset of the permission bits that are
  13         granted to the user.
  14 [/introduction]
  15
  16 [subcommand add]
  17         purpose = add or update audio files
  18         non-opts-name = path...
  19         aux_info = AFS_READ | AFS_WRITE
  20         [description]
  21                 Each path must be absolute and refer to either an audio file or a
  22                 directory. In case of a directory, all audio files in that directory
  23                 are added recursively. Note that the given paths refer to files or
  24                 directories on the host on which para_server is running.
  25         [/description]
  26         [option all]
  27                 short_opt = a
  28                 summary = add all files
  29                 [help]
  30                         The default is to add only files ending in a known suffix for a
  31                         supported audio format.
  32                 [/help]
  33         [option lazy]
  34                 short_opt = l
  35                 summary = add files lazily
  36                 [help]
  37                         If the path already exists in the database, skip this file. This
  38                         operation is really cheap. Useful to update large directories after
  39                         some files have been added.
  40                 [/help]
  41         [option force]
  42                 short_opt = f
  43                 summary = force adding/updating
  44                 [help]
  45                         Recompute the audio format handler data even if a file with the same
  46                         path and the same hash value exists.
  47                 [/help]
  48         [option verbose]
  49                 short_opt = v
  50                 summary = enable verbose mode
  51                 [help]
  52                         Print what is being done.
  53                 [/help]
  54
  55 [subcommand ff]
  56         purpose = jump N seconds forward or backward
  57         synopsis = n[-]
  58         aux_info = VSS_READ | VSS_WRITE
  59         [description]
  60                 This sets the 'R' (reposition request) bit of the vss status flags
  61                 which enqueues a request to jump n seconds forwards or backwards.
  62
  63                 Example:
  64
  65                      para_client ff 30-
  66
  67                 jumps 30 seconds backwards.
  68
  69         [/description]
  70
  71 [subcommand help]
  72         purpose = list available commands or print command-specific help
  73         non-opts-name = [command]
  74         aux_info = NO_PERMISSION_REQUIRED
  75         [description]
  76                 Without any arguments, help prints a list of available commands. When
  77                 called with a command name as first argument, it prints the description
  78                 of this command.
  79         [/description]
  80
  81 [subcommand hup]
  82         purpose = reload config file, log file and user list
  83         aux_info = VSS_WRITE
  84         [description]
  85                 Reread the config file and the user list file, close and reopen the log
  86                 file, and ask the afs process to do the same. Sending the HUP signal
  87                 to the server process has the same effect as running this command.
  88         [/description]
  89
  90 [subcommand jmp]
  91         purpose = reposition the current stream
  92         non-opts-name = n
  93         aux_info = VSS_READ | VSS_WRITE
  94         [description]
  95                 Set the 'R' (reposition request) bit of the vss status flags and
  96                 enqueue a request to jump to n% of the current audio file, where 0 <=
  97                 n <= 100.
  98         [/description]
  99
 100 [subcommand next]
 101         purpose = close the stream and start to stream the next audio file
 102         aux_info = VSS_READ | VSS_WRITE
 103         [description]
 104                 Set the 'N' (next audio file) bit of the vss status flags. This
 105                 instructs the server to close the current stream, if any. The 'P'
 106                 (playing) bit is not modified by this command. If it is on, playing
 107                 continues with the next audio file.
 108
 109                 This command is equivalent to stop if paused, and has no effect
 110                 if stopped.
 111         [/description]
 112
 113 [subcommand nomore]
 114         purpose = stop playing after current audio file
 115         aux_info = VSS_READ | VSS_WRITE
 116         [description]
 117                 Set the 'O' (no more) bit of the vss status flags which asks
 118                 para_server to clear the 'P' (playing) bit after the 'N' (next audio
 119                 file) bit transitions from off to on (because the end of the current
 120                 audio file is reached). Use this command instead of stop if you don't
 121                 like sudden endings.
 122         [/description]
 123
 124 [subcommand pause]
 125         purpose = suspend the current stream
 126         aux_info = VSS_READ | VSS_WRITE
 127         [description]
 128                 Clear the 'P' (playing) bit of the vss status flags.
 129         [/description]
 130
 131 [subcommand play]
 132         purpose = start or resume playback
 133         aux_info = VSS_READ | VSS_WRITE
 134         [description]
 135                 Set the 'P' (playing) bit of the vss status flags.
 136         [/description]
 137
 138 [subcommand sender]
 139         purpose = control paraslash senders
 140         synopsis = [sender cmd [arguments]]
 141         aux_info = VSS_READ | VSS_WRITE
 142         [description]
 143                 Send a command to a specific sender. The following commands are
 144                 available, but not all senders support every command.
 145
 146                        help, on, off, add, delete, allow, deny, status.
 147
 148                 The help command prints the help text of the given sender. If no
 149                 command is given the list of available senders is shown.
 150
 151                 Example:
 152
 153                         para_client sender http help
 154
 155         [/description]
 156
 157 [subcommand si]
 158         purpose = print server info
 159         aux_info = NO_PERMISSION_REQUIRED
 160         [description]
 161                 Show server and afs PID, number of connections, uptime and more.
 162         [/description]
 163
 164 [subcommand stat]
 165         purpose = print information about the current audio file
 166         aux_info = VSS_READ
 167         [option num]
 168                 short_opt = n
 169                 summary = number of times to show the status info
 170                 arg_info = required_arg
 171                 arg_type = uint32
 172                 typestr = num
 173                 [help]
 174                         Exit after the status information has been shown num times. If this
 175                         option is not given, the command runs in an endless loop.
 176                 [/help]
 177         [option parser-friendly]
 178                 short_opt = p
 179                 summary = enable parser-friendly output
 180                 [help]
 181                         Show status item identifiers as numerical values and prefix each
 182                         status item with its size in bytes.
 183                 [/help]
 184
 185 [subcommand stop]
 186         purpose = stop playback
 187         aux_info = VSS_READ | VSS_WRITE
 188         [description]
 189                 Clear the 'P' (playing) bit and set the 'N' (next audio file) bit of
 190                 the vss status flags, effectively stopping playback.
 191         [/description]
 192
 193 [subcommand tasks]
 194         purpose = list active server tasks
 195         aux_info = NO_PERMISSION_REQUIRED
 196         [description]
 197                 For each task, print ID, status and name. This is mostly useful
 198                 for debugging.
 199         [/description]
 200
 201 [subcommand term]
 202         purpose = ask the server to terminate
 203         aux_info = VSS_READ | VSS_WRITE
 204         [description]
 205                 Shut down the server. Instead of this command, you can also send
 206                 SIGINT or SIGTERM to the para_server process. It should never be
 207                 necessary to send SIGKILL.
 208         [/description]
 209
 210 [subcommand version]
 211         purpose = print the git version string of para_server
 212         aux_info = NO_PERMISSION_REQUIRED
 213         [option verbose]
 214                 short_opt = v
 215                 summary = print detailed (multi-line) version text
 216