Update manpages to mention new --log-file option.

Move vlog option descriptions into a separate file lib/vlog.man that
is substituted into manpages.

Get rid of individual rules for substituting most files in favor of
a single suffix rule.  Unfortunately this loses the (Emacs-specific)
read-only markings but it simplifies the makefiles.

diff --git a/Makefile.am b/Makefile.am
index bb69db7..8634a21 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -27,6 +27,7 @@ else
 AM_LDFLAGS = -export-dynamic
 endif
 
+CLEANFILES =
 DISTCLEANFILES =
 EXTRA_DIST =
 TESTS =
@@ -40,14 +41,18 @@ noinst_LIBRARIES =
 noinst_PROGRAMS =
 noinst_SCRIPTS =
 
-do_subst = sed -e 's,[@]PKIDIR[@],$(PKIDIR),g' \
-               -e 's,[@]RUNDIR[@],$(RUNDIR),g' \
-               -e 's,[@]PERL[@],$(PERL),g'
+EXTRA_DIST += README.hwtables
+
+do_subst = ($(srcdir)/subst VLOG_OPTIONS $(srcdir)/lib/vlog.man | \
+           sed -e 's,[@]PKIDIR[@],$(PKIDIR),g' \
+                -e 's,[@]RUNDIR[@],$(RUNDIR),g' \
+                -e 's,[@]PERL[@],$(PERL),g')
 ro_script = sed "`printf '1a\\' && printf '\\n\# -*- buffer-read-only: t -*-'`"
-ro_man = printf '.\\" Local\040variables:\n.\\" buffer-read-only: t\n.\\" End:\n'
 ro_c = echo '/* -*- mode: c; buffer-read-only: t -*- */'
 
-EXTRA_DIST += README.hwtables
+SUFFIXES = .in
+.in:
+       $(do_subst) < $< > $@
 
 include lib/automake.mk
 include secchan/automake.mk

diff --git a/controller/automake.mk b/controller/automake.mk
index b6c2291..ff9f627 100644 (file)
--- a/controller/automake.mk
+++ b/controller/automake.mk
@@ -6,7 +6,3 @@ controller_controller_SOURCES = controller/controller.c
 controller_controller_LDADD = lib/libopenflow.a $(FAULT_LIBS) $(SSL_LIBS)
 
 EXTRA_DIST += controller/controller.8.in
-controller/controller.8: controller/controller.8.in Makefile
-       ($(do_subst) && $(ro_man)) \
-               < $(srcdir)/controller/controller.8.in \
-               > controller/controller.8

diff --git a/controller/controller.8.in b/controller/controller.8.in
index f7f265c..b608c93 100644 (file)
--- a/controller/controller.8.in
+++ b/controller/controller.8.in
@@ -150,29 +150,7 @@ run as a background process.
 .BR \-h ", " \-\^\-help
 Prints a brief help message to the console.
 
-.TP
-\fB-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
-Sets the logging level for \fImodule\fR in \fIfacility\fR to
-\fIlevel\fR.  The \fImodule\fR may be any valid module name (as
-displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
-special name \fBANY\fR to set the logging levels for all modules.  The
-\fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
-for logging to the system log or to the console, respectively, or
-\fBANY\fR to set the logging levels for both facilities.  If it is
-omitted, \fIfacility\fR defaults to \fBANY\fR.  The \fIlevel\fR must
-be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating
-the minimum severity of a message for it to be logged.  If it is
-omitted, \fIlevel\fR defaults to \fBdbg\fR.
-
-.TP
-\fB-v\fR, \fB--verbose\fR
-Sets the maximum logging verbosity level, equivalent to
-\fB--verbose=ANY:ANY:dbg\fR.
-
-.TP
-\fB-vPATTERN:\fIfacility\fB:\fIpattern\fR, \fB--verbose=PATTERN:\fIfacility\fB:\fIpattern\fR
-Sets the log pattern for \fIfacility\fR to \fIpattern\fR.  Refer to
-\fBvlogconf\fR(8) for a description of the valid syntax for \fIpattern\fR.
+@VLOG_OPTIONS@
 
 .TP
 .BR \-V ", " \-\^\-version

diff --git a/debian/openflow-common.manpages b/debian/openflow-common.manpages
index ee20d1e..fbb8820 100644 (file)
--- a/debian/openflow-common.manpages
+++ b/debian/openflow-common.manpages
@@ -1,2 +1,2 @@
-utilities/vlogconf.8
+_debian/utilities/vlogconf.8
 _debian/utilities/ofp-pki.8

diff --git a/debian/openflow-switch.manpages b/debian/openflow-switch.manpages
index b012d8d..e50d997 100644 (file)
--- a/debian/openflow-switch.manpages
+++ b/debian/openflow-switch.manpages
@@ -3,4 +3,4 @@ _debian/secchan/secchan.8
 _debian/switch/switch.8
 _debian/utilities/ofp-discover.8
 _debian/utilities/ofp-kill.8
-utilities/dpctl.8
+_debian/utilities/dpctl.8

diff --git a/lib/automake.mk b/lib/automake.mk
index 1d0f8fa..7b4da91 100644 (file)
--- a/lib/automake.mk
+++ b/lib/automake.mk
@@ -60,6 +60,7 @@ EXTRA_DIST += \
        lib/dh4096.pem \
        lib/dhparams.h
 
+CLEANFILES += lib/dirs.c
 lib/dirs.c: Makefile
        ($(ro_c) && \
         echo 'const char ofp_rundir[] = "@RUNDIR@";' && \

diff --git a/lib/vlog.man b/lib/vlog.man
new file mode 100644 (file)
index 0000000..6bc7d29
--- /dev/null
+++ b/lib/vlog.man
@@ -0,0 +1,45 @@
+.TP
+\fB-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
+
+Sets the logging level for \fImodule\fR in \fIfacility\fR to
+\fIlevel\fR:
+
+.RS
+.IP \(bu
+\fImodule\fR may be any valid module name (as displayed by the
+\fB--list\fR action on \fBvlogconf\fR(8)), or the special name
+\fBANY\fR to set the logging levels for all modules.
+
+.IP \(bu
+\fIfacility\fR may be \fBsyslog\fR, \fBconsole\fR, or \fBfile\fR to
+set the levels for logging to the system log, the console, or a file
+respectively, or \fBANY\fR to set the logging levels for both
+facilities.  If it is omitted, \fIfacility\fR defaults to \fBANY\fR.
+
+Regardless of the log levels set for \fBfile\fR, logging to a file
+will not take place unless \fB--log-file\fR is also specified (see
+below).
+
+.IP \(bu 
+\fIlevel\fR must be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or
+\fBdbg\fR, designating the minimum severity of a message for it to be
+logged.  If it is omitted, \fIlevel\fR defaults to \fBdbg\fR.
+.RE
+
+.TP
+\fB-v\fR, \fB--verbose\fR
+Sets the maximum logging verbosity level, equivalent to
+\fB--verbose=ANY:ANY:dbg\fR.
+
+.TP
+\fB-vPATTERN:\fIfacility\fB:\fIpattern\fR, \fB--verbose=PATTERN:\fIfacility\fB:\fIpattern\fR
+Sets the log pattern for \fIfacility\fR to \fIpattern\fR.  Refer to
+\fBvlogconf\fR(8) for a description of the valid syntax for \fIpattern\fR.
+
+.TP
+\fB--log-file\fR[\fB=\fIfile\fR]
+Enables logging to a file.  If \fIfile\fR is specified, then it is
+used as the exact name for the log file.  The default log file name
+used if \fIfile\fR is omitted is @LOGDIR@/\fIprogram\fR.log, where
+\fIprogram\fR is the name of the program as invoked
+(e.g. \fBsecchan\fR).

diff --git a/secchan/automake.mk b/secchan/automake.mk
index 3c57d7f..fb4662d 100644 (file)
--- a/secchan/automake.mk
+++ b/secchan/automake.mk
@@ -6,6 +6,3 @@ secchan_secchan_LDADD = lib/libopenflow.a $(FAULT_LIBS) $(SSL_LIBS)
 
 EXTRA_DIST += secchan/secchan.8.in
 DISTCLEANFILES += secchan/secchan.8
-secchan/secchan.8: secchan/secchan.8.in Makefile
-       ($(do_subst) && $(ro_man)) \
-               < $(srcdir)/secchan/secchan.8.in > secchan/secchan.8

diff --git a/secchan/secchan.8.in b/secchan/secchan.8.in
index d7dd9b8..cc14d61 100644 (file)
--- a/secchan/secchan.8.in
+++ b/secchan/secchan.8.in
@@ -422,29 +422,7 @@ run as a background process.
 .BR \-h ", " \-\^\-help
 Prints a brief help message to the console.
 
-.TP
-\fB-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
-Sets the logging level for \fImodule\fR in \fIfacility\fR to
-\fIlevel\fR.  The \fImodule\fR may be any valid module name (as
-displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
-special name \fBANY\fR to set the logging levels for all modules.  The
-\fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
-for logging to the system log or to the console, respectively, or
-\fBANY\fR to set the logging levels for both facilities.  If it is
-omitted, \fIfacility\fR defaults to \fBANY\fR.  The \fIlevel\fR must
-be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating
-the minimum severity of a message for it to be logged.  If it is
-omitted, \fIlevel\fR defaults to \fBdbg\fR.
-
-.TP
-\fB-v\fR, \fB--verbose\fR
-Sets the maximum logging verbosity level, equivalent to
-\fB--verbose=ANY:ANY:dbg\fR.
-
-.TP
-\fB-vPATTERN:\fIfacility\fB:\fIpattern\fR, \fB--verbose=PATTERN:\fIfacility\fB:\fIpattern\fR
-Sets the log pattern for \fIfacility\fR to \fIpattern\fR.  Refer to
-\fBvlogconf\fR(8) for a description of the valid syntax for \fIpattern\fR.
+@VLOG_OPTIONS@
 
 .TP
 .BR \-V ", " \-\^\-version

diff --git a/subst b/subst
new file mode 100755 (executable)
index 0000000..c2e71df
--- /dev/null
+++ b/subst
@@ -0,0 +1,5 @@
+#! /bin/sh
+exec sed -e "/^@$1@\$/{
+r $2
+d
+}"

diff --git a/switch/automake.mk b/switch/automake.mk
index 58e13c9..d9826f4 100644 (file)
--- a/switch/automake.mk
+++ b/switch/automake.mk
@@ -23,6 +23,3 @@ switch_switch_LDADD = lib/libopenflow.a $(FAULT_LIBS) $(SSL_LIBS)
 
 EXTRA_DIST += switch/switch.8.in
 DISTCLEANFILES += switch/switch.8
-switch/switch.8: switch/switch.8.in Makefile
-       ($(do_subst) && $(ro_man)) \
-               < $(srcdir)/switch/switch.8.in > switch/switch.8

diff --git a/switch/switch.8.in b/switch/switch.8.in
index 4b3584e..c6aa606 100644 (file)
--- a/switch/switch.8.in
+++ b/switch/switch.8.in
@@ -110,29 +110,7 @@ run as a background process.
 .BR \-h ", " \-\^\-help
 Prints a brief help message to the console.
 
-.TP
-\fB-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
-Sets the logging level for \fImodule\fR in \fIfacility\fR to
-\fIlevel\fR.  The \fImodule\fR may be any valid module name (as
-displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
-special name \fBANY\fR to set the logging levels for all modules.  The
-\fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
-for logging to the system log or to the console, respectively, or
-\fBANY\fR to set the logging levels for both facilities.  If it is
-omitted, \fIfacility\fR defaults to \fBANY\fR.  The \fIlevel\fR must
-be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating
-the minimum severity of a message for it to be logged.  If it is
-omitted, \fIlevel\fR defaults to \fBdbg\fR.
-
-.TP
-\fB-v\fR, \fB--verbose\fR
-Sets the maximum logging verbosity level, equivalent to
-\fB--verbose=ANY:ANY:dbg\fR.
-
-.TP
-\fB-vPATTERN:\fIfacility\fB:\fIpattern\fR, \fB--verbose=PATTERN:\fIfacility\fB:\fIpattern\fR
-Sets the log pattern for \fIfacility\fR to \fIpattern\fR.  Refer to
-\fBvlogconf\fR(8) for a description of the valid syntax for \fIpattern\fR.
+@VLOG_OPTIONS@
 
 .TP
 .BR \-V ", " \-\^\-version

diff --git a/utilities/automake.mk b/utilities/automake.mk
index e359d5f..f9ce28d 100644 (file)
--- a/utilities/automake.mk
+++ b/utilities/automake.mk
@@ -7,25 +7,28 @@ bin_SCRIPTS += utilities/ofp-pki
 noinst_SCRIPTS += utilities/ofp-pki-cgi
 
 EXTRA_DIST += \
+       utilities/dpctl.8.in \
        utilities/ofp-discover.8.in \
        utilities/ofp-kill.8.in \
        utilities/ofp-pki-cgi.in \
        utilities/ofp-pki.8.in \
-       utilities/ofp-pki.in
+       utilities/ofp-pki.in \
+       utilities/vlogconf.8.in
 DISTCLEANFILES += \
+       utilities/dpctl.8 \
        utilities/ofp-discover.8 \
        utilities/ofp-kill.8 \
        utilities/ofp-pki \
+       utilities/ofp-pki.8 \
        utilities/ofp-pki-cgi \
-       utilities/ofp-pki.8
+       utilities/vlogconf.8
 
-dist_man_MANS += \
-       utilities/vlogconf.8 \
-       utilities/dpctl.8
 man_MANS += \
-       utilities/ofp-pki.8 \
+       utilities/dpctl.8 \
        utilities/ofp-discover.8 \
-       utilities/ofp-kill.8
+       utilities/ofp-kill.8 \
+       utilities/ofp-pki.8 \
+       utilities/vlogconf.8
 
 utilities_dpctl_SOURCES = utilities/dpctl.c
 utilities_dpctl_LDADD = lib/libopenflow.a $(FAULT_LIBS) $(SSL_LIBS)
@@ -38,21 +41,3 @@ utilities_ofp_discover_LDADD = lib/libopenflow.a
 
 utilities_ofp_kill_SOURCES = utilities/ofp-kill.c
 utilities_ofp_kill_LDADD = lib/libopenflow.a
-
-utilities/ofp-pki: utilities/ofp-pki.in Makefile
-       $(do_subst) < $(srcdir)/utilities/ofp-pki.in \
-               | $(ro_script) > utilities/ofp-pki
-       chmod +x utilities/ofp-pki
-utilities/ofp-pki-cgi: utilities/ofp-pki-cgi.in Makefile
-       $(do_subst) < $(srcdir)/utilities/ofp-pki-cgi.in \
-               | $(ro_script) > utilities/ofp-pki-cgi
-       chmod +x utilities/ofp-pki-cgi
-utilities/ofp-pki.8: utilities/ofp-pki.8.in Makefile
-       ($(do_subst) && $(ro_man)) \
-               < $(srcdir)/utilities/ofp-pki.8.in > utilities/ofp-pki.8
-utilities/ofp-discover.8: utilities/ofp-discover.8.in Makefile
-       ($(do_subst) && $(ro_man)) < $(srcdir)/utilities/ofp-discover.8.in \
-               > utilities/ofp-discover.8
-utilities/ofp-kill.8: utilities/ofp-kill.8.in Makefile
-       ($(do_subst) && $(ro_man)) < $(srcdir)/utilities/ofp-kill.8.in \
-               > utilities/ofp-kill.8

diff --git a/utilities/dpctl.8 b/utilities/dpctl.8.in
similarity index 93%
rename from utilities/dpctl.8
rename to utilities/dpctl.8.in
index c780593..2ab5f32 100644 (file)
--- a/utilities/dpctl.8
+++ b/utilities/dpctl.8.in
@@ -429,29 +429,7 @@ a switch is trustworthy.
 .BR \-h ", " \-\^\-help
 Prints a brief help message to the console.
 
-.TP
-\fB-v\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
-Sets the logging level for \fImodule\fR in \fIfacility\fR to
-\fIlevel\fR.  The \fImodule\fR may be any valid module name (as
-displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
-special name \fBANY\fR to set the logging levels for all modules.  The
-\fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
-for logging to the system log or to the console, respectively, or
-\fBANY\fR to set the logging levels for both facilities.  If it is
-omitted, \fIfacility\fR defaults to \fBANY\fR.  The \fIlevel\fR must
-be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating
-the minimum severity of a message for it to be logged.  If it is
-omitted, \fIlevel\fR defaults to \fBdbg\fR.
-
-.TP
-\fB-v\fR, \fB--verbose\fR
-Sets the maximum logging verbosity level, equivalent to
-\fB--verbose=ANY:ANY:dbg\fR.
-
-.TP
-\fB-vPATTERN:\fIfacility\fB:\fIpattern\fR, \fB--verbose=PATTERN:\fIfacility\fB:\fIpattern\fR
-Sets the log pattern for \fIfacility\fR to \fIpattern\fR.  Refer to
-\fBvlogconf\fR(8) for a description of the valid syntax for \fIpattern\fR.
+@VLOG_OPTIONS@
 
 .TP
 .BR \-V ", " \-\^\-version

diff --git a/utilities/ofp-discover.8.in b/utilities/ofp-discover.8.in
index e2ba8b2..304c3c7 100644 (file)
--- a/utilities/ofp-discover.8.in
+++ b/utilities/ofp-discover.8.in
@@ -97,29 +97,7 @@ effect.
 .BR \-h ", " \-\^\-help
 Prints a brief help message to the console.
 
-.TP
-\fB-v\fR \fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]], \fB--verbose=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]
-Sets the logging level for \fImodule\fR in \fIfacility\fR to
-\fIlevel\fR.  The \fImodule\fR may be any valid module name (as
-displayed by the \fB--list\fR action on \fBvlogconf\fR(8)), or the
-special name \fBANY\fR to set the logging levels for all modules.  The
-\fIfacility\fR may be \fBsyslog\fR or \fBconsole\fR to set the levels
-for logging to the system log or to the console, respectively, or
-\fBANY\fR to set the logging levels for both facilities.  If it is
-omitted, \fIfacility\fR defaults to \fBANY\fR.  The \fIlevel\fR must
-be one of \fBemer\fR, \fBerr\fR, \fBwarn\fR, or \fBdbg\fR, designating
-the minimum severity of a message for it to be logged.  If it is
-omitted, \fIlevel\fR defaults to \fBdbg\fR.
-
-.TP
-\fB-v\fR, \fB--verbose\fR
-Sets the maximum logging verbosity level, equivalent to
-\fB--verbose=ANY:ANY:dbg\fR.
-
-.TP
-\fB-vPATTERN:\fIfacility\fB:\fIpattern\fR, \fB--verbose=PATTERN:\fIfacility\fB:\fIpattern\fR
-Sets the log pattern for \fIfacility\fR to \fIpattern\fR.  Refer to
-\fBvlogconf\fR(8) for a description of the valid syntax for \fIpattern\fR.
+@VLOG_OPTIONS@
 
 .TP
 .BR \-V ", " \-\^\-version

diff --git a/utilities/vlogconf.8 b/utilities/vlogconf.8.in
similarity index 81%
rename from utilities/vlogconf.8
rename to utilities/vlogconf.8.in
index 7298d29..f1acf62 100644 (file)
--- a/utilities/vlogconf.8
+++ b/utilities/vlogconf.8.in
@@ -15,6 +15,7 @@ The available \fIaction\fR options are:
 [\fB-l\fR | \fB--list\fR] [\fB-s\fR
 \fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]] |
 \fB--set=\fImodule\fR[\fB:\fIfacility\fR[\fB:\fIlevel\fR]]]
+[\fB-r\fR | \fB--reopen\fR]
 
 .SH DESCRIPTION
 The \fBvlogconf\fR program configures the logging system used by 
@@ -29,11 +30,31 @@ target processes.  Targets may be specified as:
 All running processes that \fBvlogconf\fR can control.
 
 .TP
-\fB-t \fIpid\fR, \fB--target=\fIpid\fR
-The process with the specified \fIpid\fR.  \fIpid\fR may also specify
-an absolute path (beginning with `/') to the Unix domain socket for a
+\fB-t \fItarget\fR, \fB--target=\fItarget\fR
+The specified \fItarget\fR, which must take one of the following forms:
+
+.RS
+.IP \(bu
+A PID (process ID).
+
+.IP \(bu
+An absolute path (beginning with `/') to the Unix domain socket for a
 \fBvlogconf\fR-controllable process.
 
+.IP \(bu
+An absolute path (beginning with `/') to a pidfile (created by, e.g.,
+passing the \fB-P\fR or \fB--pidfile\fR option to one of the OpenFlow
+programs).  
+
+.IP \(bu
+None of the above, in which case \fItarget\fR prefixed by
+\fB@RUNDIR@/\fR must match one of the cases for absolute paths listed
+above.  (The default name for a program's pidfile is
+\fB@RUNDIR@/\fIprogram\fB.pid\fR, so this means that, say,
+\fBsecchan\fR's default pidfile may be referred to simply as
+\fBsecchan.pid\fR.)
+.RE
+
 .PP
 The available actions are:
 
@@ -143,6 +164,12 @@ width.  (A field wider than \fIwidth\fR is not truncated to fit.)
 The default pattern for console output is \fB%d{%b %d
 %H:%M:%S}|%05N|%c|%p|%m\fR; for syslog output, \fB%05N|%c|%p|%m\fR.
 
+.TP
+\fB-r\fR, \fB--reopen\fR
+Causes the target application to close and reopen its log file.  (This
+is useful after rotating log files, to cause a new log file to be
+used.)
+
 .SH OPTIONS
 .TP
 \fB\-h\fR, \fB\-\^\-help\fR