From 9795d7d750d84e2fdc86a6c737f2bf07f0efef80 Mon Sep 17 00:00:00 2001 From: Ben Pfaff Date: Thu, 23 Oct 2008 14:03:44 -0700 Subject: [PATCH] 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. --- Makefile.am | 15 ++++++--- controller/automake.mk | 4 --- controller/controller.8.in | 24 +------------ debian/openflow-common.manpages | 2 +- debian/openflow-switch.manpages | 2 +- lib/automake.mk | 1 + lib/vlog.man | 45 +++++++++++++++++++++++++ secchan/automake.mk | 3 -- secchan/secchan.8.in | 24 +------------ subst | 5 +++ switch/automake.mk | 3 -- switch/switch.8.in | 24 +------------ utilities/automake.mk | 35 ++++++------------- utilities/{dpctl.8 => dpctl.8.in} | 24 +------------ utilities/ofp-discover.8.in | 24 +------------ utilities/{vlogconf.8 => vlogconf.8.in} | 33 ++++++++++++++++-- 16 files changed, 108 insertions(+), 160 deletions(-) create mode 100644 lib/vlog.man create mode 100755 subst rename utilities/{dpctl.8 => dpctl.8.in} (93%) rename utilities/{vlogconf.8 => vlogconf.8.in} (81%) diff --git a/Makefile.am b/Makefile.am index bb69db7a..8634a218 100644 --- 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 b6c2291a..ff9f627c 100644 --- 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 f7f265c3..b608c939 100644 --- 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 ee20d1ea..fbb88201 100644 --- 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 b012d8db..e50d9978 100644 --- 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 1d0f8fab..7b4da911 100644 --- 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 index 00000000..6bc7d298 --- /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 3c57d7f8..fb4662d0 100644 --- 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 d7dd9b81..cc14d61e 100644 --- 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 index 00000000..c2e71df8 --- /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 58e13c9d..d9826f4c 100644 --- 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 4b3584e9..c6aa6060 100644 --- 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 e359d5fa..f9ce28d6 100644 --- 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 c7805932..2ab5f327 100644 --- 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 e2ba8b2d..304c3c7d 100644 --- 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 7298d29d..f1acf62b 100644 --- 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 -- 2.30.2