TT#55050 man page updates

Adds rtpengine-recording man page and adds some missing arguments from
rtpengine.8

Change-Id: I054d1bcad08e6070cca41008f740c0cbecb15fa8

daemon/rtpengine.pod

@@ -37,7 +37,7 @@ version number and exit.
 
 Print a list of supported codecs and exit.
 
-=item B<--config-file>
+=item B<--config-file=>I<FILE>
 
 Specifies the location of a config file to be used. The config file is an
 I<.ini> style config file, with all command-line options listed here also
@@ -56,7 +56,7 @@ semicolons (see section L<INTERFACES> below for an example).
 As a special value, B<none> can be passed here to suppress loading of the
 default config file.
 
-=item B<--config-section>
+=item B<--config-section=>I<STRING>
 
 Specifies the I<.ini> style section to be used in the config file.
 Multiple sections can be present in the config file, but only one can be
@@ -194,9 +194,9 @@ Default to 30000 and 40000 respectively.
 
 Takes an integer as argument and controls the highest log level which
 will be sent to syslog.
-The log levels correspond to the ones found in the syslog(3) man page.
-The default value is 6, equivalent to LOG_INFO.
-The highest possible value is 7 (LOG_DEBUG) which will log everything.
+The log levels correspond to the ones found in the L<syslog(3)> man page.
+The default value is B<6>, equivalent to LOG_INFO.
+The highest possible value is B<7> (LOG_DEBUG) which will log everything.
 
 During runtime, the log level can be decreased by sending the signal
 SIGURS1 to the daemon and can be increased with the signal SIGUSR2.
@@ -256,12 +256,12 @@ Only useful in combination with B<--foreground>.
 Don't add timestamps to log lines written to stderr.
 Only useful in combination with B<--log-stderr>.
 
-=item B<--log-mark-prefix>
+=item B<--log-mark-prefix=>I<STRING>
 
 Prefix to be added to particular data fields in log files that are deemed
 sensitive and/or private information. Defaults to an empty string.
 
-=item B<--log-mark-suffix>
+=item B<--log-mark-suffix=>I<STRING>
 
 Suffix to be added to particular data fields in log files that are deemed
 sensitive and/or private information. Defaults to an empty string.
@@ -296,7 +296,7 @@ old behaviour.
 
 Enables the B<DTLS=passive> flag for all calls unconditionally.
 
-=item B<-d>, B<--delete-delay>
+=item B<-d>, B<--delete-delay=>I<INT>
 
 Delete the call from memory after the specified delay from memory.
 Can be set to zero for immediate call deletion.
@@ -340,7 +340,7 @@ password is B<RTPENGINE_REDIS_WRITE_AUTH_PW>.
 When both options are given, B<rtpengine> will start and use the Redis
 database regardless of the database's role (master or slave).
 
-=item B<-k>, B<--subscribe-keyspace>
+=item B<-k>, B<--subscribe-keyspace=>I<INT>
 
 List of redis keyspaces to subscribe.
 If this is not present, no keyspaces are subscribed (default behaviour).

debian/ngcp-rtpengine-recording-daemon.manpages

@@ -0,0 +1 @@
+recording-daemon/rtpengine-recording.8

recording-daemon/.gitignore

@@ -17,3 +17,4 @@ ssllib.c
 dtmflib.c
 *-test
 *-test.c
+*.8

recording-daemon/Makefile

@@ -30,6 +30,9 @@ LIBSRCS=	loglib.c auxlib.c rtplib.c codeclib.c resample.c str.c socket.c streamb
 		dtmflib.c
 OBJS=		$(SRCS:.c=.o) $(LIBSRCS:.c=.o)
 
+PODS=		rtpengine-recording.pod
+MANS=		$(PODS:.pod=.8)
+
 include ../lib/common.Makefile
 
 include		.depend

recording-daemon/rtpengine-recording.pod

@@ -0,0 +1,223 @@
+=head1 NAME
+
+rtpengine-recording - media recording daemon for Sipwise rtpengine
+
+=head1 SYNOPSIS
+
+B<rtpengine-recording> [I<option>...]
+
+=head1 DESCRIPTION
+
+The Sipwise rtpengine media proxy has support for exporting media (RTP) packets
+that it forwards. The rtpengine-recording daemon collects these exported
+packets and decodes them into an audio format that can be listened to.
+
+=head1 OPTIONS
+
+All options can (and should) be provided in a config file instead of
+at the command line. See the B<--config-file> option below for details.
+
+If no options are given, then default values are assumed, which should be
+sufficient for a standard installation of rtpengine.
+
+=over 4
+
+=item B<--help>
+
+Print the usage information.
+
+=item B<-v>, B<--version>
+
+If called with this option, the B<rtpengine-recording> daemon will simply print
+its version number and exit.
+
+=item B<--config-file=>I<FILE>
+
+Specifies the location of a config file to be used. The config file is an
+I<.ini> style config file, with all command-line options listed here also
+being valid options in the config file.
+For all command-line options, the long name version instead of the
+single-character version (e.g. B<table> instead of just B<t>) must be
+used in the config file.
+For boolean options that are either present or not (e.g. B<output-mixed>), a
+boolean value (either B<true> or B<false>) must be used in the config file.
+If an option is given in both the config file and at the command line,
+the command-line value overrides the value from the config file.
+
+As a special value, B<none> can be passed here to suppress loading of the
+default config file.
+
+=item B<--config-section=>I<STRING>
+
+Specifies the I<.ini> style section to be used in the config file.
+Multiple sections can be present in the config file, but only one can be
+used at a time.
+The default value is B<rtpengine-recording>.
+A config file section is started in the config file using square brackets
+(e.g. B<[rtpengine-recording]>).
+
+=item B<-L>, B<--log-level=>I<INT>
+
+Takes an integer as argument and controls the highest log level which
+will be sent to syslog.
+The log levels correspond to the ones found in the L<syslog(3)> man page.
+The default value is B<6>, equivalent to LOG_INFO.
+The highest possible value is B<7> (LOG_DEBUG) which will log everything.
+
+=item B<--log-facilty=>B<daemon>|B<local0>|...|B<local7>|...
+
+The syslog facilty to use when sending log messages to the syslog daemon.
+Defaults to B<daemon>.
+
+=item B<-E>, B<--log-stderr>
+
+Log to stderr instead of syslog.
+Only useful in combination with B<--foreground>.
+
+=item B<--no-log-timestamps>
+
+Don't add timestamps to log lines written to stderr.
+Only useful in combination with B<--log-stderr>.
+
+=item B<--log-mark-prefix=>I<STRING>
+
+Prefix to be added to particular data fields in log files that are deemed
+sensitive and/or private information. Defaults to an empty string.
+
+=item B<--log-mark-suffix=>I<STRING>
+
+Suffix to be added to particular data fields in log files that are deemed
+sensitive and/or private information. Defaults to an empty string.
+
+=item B<-p>, B<--pidfile=>I<FILE>
+
+Specifies a path and file name to write the daemon's PID number to.
+
+=item B<-f>, B<--foreground>
+
+If given, prevents the daemon from daemonizing, meaning it will stay in
+the foreground.
+Useful for debugging.
+
+=item B<-t>, B<--table=>I<INT>
+
+Takes an integer argument. The value must match the B<table> option given to
+the B<rtpengine> media proxy to use for in-kernel packet forwarding.
+Defaults to B<0> if not specified.
+
+=item B<--spool-dir=>I<PATH>
+
+The path given here must match the B<recording-dir> path given to the
+B<rtpengine> media proxy. Defaults to F</var/spool/rtpengine>. The path must
+reside on a file system that supports the B<inotify> mechanism.
+
+=item B<--num-threads=>I<INT>
+
+How many worker threads to launch. Defaults to B<8>.
+
+=item B<--output-storage=>B<file>|B<db>|B<both>
+
+Where to store media files. By default, media files are written directly to the
+file system (see B<output-dir>). They can also be stored as a B<BLOB> in a
+MySQL database, either instead of, or in addition to, being written to the file
+system.
+
+=item B<--output-dir=>I<PATH>
+
+Path for media files to be written to if file output is enabled. Defaults to
+F</var/lib/rtpengine-recording>. The path must not be the same as used for the
+B<spool-dir>.
+
+=item B<--output-format=>B<wav>|B<mp3>|B<none>
+
+File format to be used for media files that are produced. Defaults to PCM WAV
+(RIFF) files. Applicable for both files stored on the file system and in a
+database. If B<none> is selected then file output is disabled.
+
+=item B<--resample-to=>I<INT>
+
+Resample all audio to the given sample rate (e.g. B<48000>). Resampling is
+disabled by default, meaning that files will be written with the same sample
+rate as the source media.
+
+=item B<--mp3-bitrate=>I<INT>
+
+If MP3 output is selected, use the given bitrate for the MP3 encoder (e.g.
+B<64000>). There is no default value, so this option must be given if MP3
+output is selected. Note that not all bitrates are valid in combinations with
+all sample rates. For MP3 output it's therefore recommended to also set
+B<resample-to>.
+
+=item B<--output-mixed>
+
+=item B<--output-single>
+
+Whether to produce B<mixed> audio files, or B<single> audio files, or both. If
+neither option is given, then by default both are enabled. If no file output is
+desired, set B<output-format> to B<none>.
+
+A B<single> audio file contains the audio for a single RTP SSRC, which usually
+means an unidirectional audio stream. These are decoded directly from an RTP
+stream and do not take timestamping into account, meaning that gaps or pauses
+in the RTP stream are not reflected in the output audio file.
+
+A B<mixed> audio file consists of the first four RTP SSRC seen, mixed together
+into a single output file, which usually means that a bidirectional audio
+stream is produced. Audio mixing takes RTP timestamping into account, so gaps
+and pauses in the RTP media are reflected in the output audio to keep the
+multiple audio sources in sync.
+
+=item B<--mysql-host=>I<HOST>|I<IP>
+
+=item B<--mysql-port=>I<INT>
+
+=item B<--mysql-user=>I<USERNAME>
+
+=item B<--mysql-pass=>I<PASSWORD>
+
+=item B<--mysql-db=>I<STRING>
+
+Configuration for a MySQL storage backend. Details about calls and media files
+that are produced are stored into the database. Optionally the media files
+themselves can be stored as well (see B<output-storage>).
+
+=item B<--forward-to=>I<PATH>
+
+Forward raw RTP packets to a Unix socket. Disabled by default.
+
+=item B<--tls-send-to=>I<IP>B<:>I<PORT>
+
+=item B<--tls-resample=>I<INT>
+
+Send decoded audio over a TCP TLS connection to the specified destination.
+Audio is sent as raw mono 16-bit PCM in the given sample rate.
+
+=back
+
+=head1 EXIT STATUS
+
+=over
+
+=item B<0>
+
+Successful termination.
+
+=item B<1>
+
+An error occurred.
+
+=back
+
+=head1 FILES
+
+=over
+
+=item F</etc/rtpengine/rtpengine-recording.conf>
+
+Configuration file.
+
+=back
+
+=head1 SEE ALSO
+
+L<rtpengine(8)>.