From 76cd4baec8f5c266c8047cc88981f84701e1fc7a Mon Sep 17 00:00:00 2001 From: Jeffrey Hutzelman Date: Thu, 21 Feb 2013 19:25:18 -0500 Subject: Substitute paths into man pages Generate the man pages for zwgc, zctl, zhm, and zephyrd at build time, so they can refer to the paths actually used instead of whatever was used on Athena in the 1980's. --- clients/zctl/Makefile.in | 13 +- clients/zctl/zctl.1 | 311 ----------------------------------------------- clients/zctl/zctl.1.in | 311 +++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 323 insertions(+), 312 deletions(-) delete mode 100644 clients/zctl/zctl.1 create mode 100644 clients/zctl/zctl.1.in (limited to 'clients') diff --git a/clients/zctl/Makefile.in b/clients/zctl/Makefile.in index 105fe10..fa8d4ae 100644 --- a/clients/zctl/Makefile.in +++ b/clients/zctl/Makefile.in @@ -22,6 +22,12 @@ LIBTOOL=@LIBTOOL@ CC=@CC@ INSTALL=@INSTALL@ +editman = sed \ + -e 's|@datadir[@]|${datadir}|g' \ + -e 's|@sysconfdir[@]|${sysconfdir}|g' \ + -e 's|@sbindir[@]|${sbindir}|g' \ + -e 's|@lsbindir[@]|${lsbindir}|g' + LIBZEPHYR=${BUILDTOP}/lib/libzephyr.la CPPFLAGS=@CPPFLAGS@ CFLAGS=@CFLAGS@ @@ -32,7 +38,7 @@ LIBS=${LIBZEPHYR} @SS_LIBS@ @LIBS@ -lcom_err SS_OBJS=zctl_cmds.o OBJS= zctl.o @SS_OBJS@ -all: zctl +all: zctl zctl.1 zctl: ${OBJS} ${LIBZEPHYR} ${LIBTOOL} --mode=link ${CC} ${LDFLAGS} -o $@ ${OBJS} ${LIBS} @@ -43,6 +49,10 @@ zctl_cmds.c: zctl_cmds.ct .c.o: ${CC} -c ${ALL_CFLAGS} $< +zctl.1: ${srcdir}/zctl.1.in Makefile + ${editman} ${srcdir}/$@.in > $@.tmp + mv $@.tmp $@ + check: install: zctl @@ -52,6 +62,7 @@ install: zctl clean: ${LIBTOOL} --mode=clean rm -f zctl rm -f ${OBJS} zctl_cmds.c + rm -f zctl.1 ${OBJS}: ${top_srcdir}/h/sysdep.h ${BUILDTOP}/h/config.h ${OBJS}: ${BUILDTOP}/h/zephyr/zephyr.h ${BUILDTOP}/h/zephyr/zephyr_err.h diff --git a/clients/zctl/zctl.1 b/clients/zctl/zctl.1 deleted file mode 100644 index c94bbf9..0000000 --- a/clients/zctl/zctl.1 +++ /dev/null @@ -1,311 +0,0 @@ -.\" $Id$ -.\" -.\" Copyright 1987,1988 by the Massachusetts Institute of Technology -.\" All rights reserved. The file /usr/include/zephyr/mit-copyright.h -.\" specifies the terms and conditions for redistribution. -.\" -.\" -.TH ZCTL 1 "July 1, 1988" "MIT Project Athena" -.ds ]W MIT Project Athena -.SH NAME -zctl \- zephyr control program -.SH SYNOPSIS -.B zctl -[ -.I options -] -.SH DESCRIPTION -.I Zctl -is a general purpose control program for the -.I Zephyr(1) -Notification Service. It allows the user to subscribe to specific -notice types, to save the subscriptions in a file (default -$HOME/.zephyr.subs), to change his location information, and to send -control messages to the HostManager, -.I zhm(8), -and the WindowGram client, -.I zwgc(1). -.PP -The commands may be typed on the command line, or may be entered -interactively by just typing -.I zctl -and then typing commands to the prompt. -.br -.B NOTE: -For all commands accepting an optional \fIrecipient\fR argument, the -\fIrecipient\fR defaults to your Kerberos principal. You may also -subscribe to recipient ``\fI*\fR''. If you specify a recipient, it is -silently converted to ``\fI*\fR''. -.br -The commands are as follows: -.TP 15 -.B add \fIclass instance\fR [ \fIrecipient\fR ] -Subscribe to \fIclass, instance, recipient\fR, and add this triplet to -the subscriptions file. -.TP -.B add_unsubscription \fIclass instance\fR [ \fIrecipient\fR ] -Unsubscribe to \fIclass, instance, recipient\fR, and add this triplet -to the subscriptions file as an un-subscription. -For an explanation of un-subscriptions, see below. -.TP -.B cancel -Cancel all subscriptions. -.TP -.B defaults -Retrieve the default subscription list from the Zephyr server. -.TP -.B delete \fIclass instance\fR [ \fIrecipient\fR ] -Unsubscribe to \fIclass, instance, recipient\fR, and remove this triplet -from the subscriptions file. -.TP -.B delete_unsubscription \fIclass instance\fR [ \fIrecipient\fR ] -Unsubscribe to \fIclass, instance, recipient\fR, and remove this triplet -from the subscriptions file as an un-subscription. -.TP -.B file \fR[ \fIfile\fR ] -Set default subscriptions file to \fIfile\fR. If \fIfile\fR isn't specified, -show what the current subscriptions file is. -.TP -.B flush_locs -Tell the Zephyr servers to flush all location information associated with -the user. This should only be used to remove any incorrect data that may have -been left after a system crash. -.TP -.B hide -Hide your location as maintained by the Zephyr server. This does not -affect the value of the exposure variable (see below, under -.B set). -.TP -.B hm_flush -Tell the HostManager, -.I zhm(8), -to ask the server to flush all state associated with the current host. -.TP -.B list \fR[ \fIfile\fR ] -List contents of current subscriptions file or -.I file. -Any macros in the file (see below) are displayed verbatim and not expanded. -.TP -.B list_requests -List all available commands. May be abbreviated by '?'. -.TP -.B load \fR[ \fIfile\fR ] -Subscribe to all subscription triplets and unsubscribe to all -un-subscription triplets in current subscriptions file or \fIfile\fR. -.TP -.B new_server -Tell the HostManager, -.I zhm(8), -to find a new Zephyr server. -.TP -.B quit -Exit from \fIzctl. -.TP -.B retrieve -Retrieve all current subscriptions from the Zephyr server. These include -subscriptions that might have been made by other programs, such as -.I znol(1). -.TP -.B save \fR[ \fIfile\fR ] -Save all current subscriptions (as returned by the Zephyr server) -into current subscriptions file or \fIfile\fR. The -file will be replaced. -.TP -.B set \fIvar\fR [ \fIvalue\fR ] -Set the value of Zephyr variable \fIvar\fR to \fIvalue\fR, or null if -no \fIvalue\fR is specified. The variable \fBexposure\fR has special -significance, and can only be set to the values none, opstaff, realm-visible, -realm-announced, net-visible, and net-announced. Setting this variable -immediately updates the information in the Zephyr servers (see below for -an explanation of the exposure levels). In addition, -setting this variable to none automatically performs the equivalent of a -.B wg_shutdown -command, and setting it to one of the other values automatically -performs the equivalent of a -.B wg_startup -command. -.br -The variable \fBresolved_addresses\fR determines whether zwgc will, -for an IP address indicating the origin of a message, attempt to look -up the hostname corresponding to that IP address. The value none -indicates that hostnames will never be found, and that the zwgc -fromhost variable will thus always contain an IP address (in -dotted-decimal form). The value all indicates that there will always -be an attempt to look up a hostname. Note that in this case, if you -have any subscriptions with recipient ``\fI*\fR'', these subscriptions -may be revealed to other Zephyr users who operate their own DNS name -servers. Any other value is interpreted as a regular expression; -hostname lookup attempts will occur only if the IP address matches -this regular expression. -.br -Any variable settings you make will be stored in \fI$HOME/.zephyr.vars\fR -.TP -.B show \fIvar\fR [ \fIvar\fR \ ... ] -Show the value of the specified Zephyr variables. If a variable is not -defined in the user's own variables file, the system variables file -(\fI/etc/athena/zephyr.vars\fR) is searched for a default value. -.TP -.B subscribe \fIclass instance\fR [ \fIrecipient\fR ] -Subscribe to \fIclass, instance, recipient\fR, but don't add this triplet to -the subscriptions file. -.TP -.B unhide -Make your location as maintained by the Zephyr server visible. This does not -affect the value of the exposure variable. -.TP -.B unload \fR[ \fIfile\fR ] -Unsubscribe to all subscription triplets in current subscriptions file -or \fIfile\fR. Un-subscriptions in the file are ignored. -.TP -.B unset \fIvar\fR [ \fIvar\fR \ ... ] -Delete the definitions of the specified Zephyr variables. -.TP -.B unsubscribe \fIclass instance\fR [ \fIrecipient\fR ] -Unsubscribe to \fIclass, instance, recipient\fR, but don't remove this triplet -from the subscriptions file. -.TP -.B wg_exit -Tell the WindowGram client, -.I zwgc(1), -to exit. -.TP -.B wg_read -Tell the WindowGram client, -.I zwgc(1), -to reread its description file. -.TP -.B wg_shutdown -Tell the WindowGram client to shutdown; this causes it to ignore all -notices until a wg_startup command is issued. -.TP -.B wg_startup -Tell the WindowGram client to start accepting notices again; useful -after a wg_shutdown command has been issued. -.SH MACROS and SUBSCRIPTION FILES -There are three macros, -.I %host%, %canon%, \fRand\fI %me%. %host% -is converted to the current hostname, \fI%canon%\fR is converted to the -official hostname as returned by -.I gethostbyname(3), -and \fI%me%\fR is converted to your Kerberos principal. These macros can be -used in your \fI$HOME/.zephyr.subs\fR file or as arguments to commands -to specify the -.I class -or -.I instance -fields. A sample \fI$HOME/.zephyr.subs\fR file might contain the following: -.PP -.nf - message,urgent,%me% - syslog,%host%,* - mail,pop,%me% -.fi -.PP -.I Zctl -reads the environment variable \fBWGFILE\fR, to find the name of the -file where the windowgram port resides. If \fBWGFILE\fR is not set, -the file name defaults to /tmp/wg.\fIuid\fR, where \fIuid\fR is the -user's UNIX uid. -.SH UN-SUBSCRIPTIONS -The zephyr server, -.I zephyrd(8), -maintains default subscriptions which are automatically added to all -users' subscriptions at the time of their first subscription during a -login session. If you wish to automatically remove some of these -default subscriptions, you use -.B un-subscriptions. -When you -.B load -a subscription file containing -un-subscriptions, the un-subscriptions are automatically sent to the -server as if you had used the -.B unsubscribe -command. -.SH EXPOSURE LEVELS -The different exposure levels affect the operation of zephyr and its -interaction with the user, as follows: -.TP 10 -.I none -This completely disables Zephyr for the user. The user is not -registered with Zephyr. No user location information is -retained by Zephyr. No login or logout announcements will be -sent. No subscriptions will be entered for the user, and no notices -will be displayed by -.I zwgc(1). -.TP -.I opstaff -The user is registered with Zephyr. No login or logout -announcements will be sent, and location information will only be -visible to Operations staff. Default subscriptions and any additional -personal subscriptions will be entered for the user. -.TP -.I realm-visible -The user is registered with Zephyr. User location information is retained by -Zephyr and made available only to users within the user's -Kerberos realm. No login or logout announcements will be sent. This -is the system default. Default subscriptions and any additional -personal subscriptions will be entered for the user. -.TP -.I realm-announced -The user is registered with Zephyr. User location information is retained by -Zephyr and made available only to users authenticated within the user's -Kerberos realm. Login and logout announcements will be sent, but only to -users within the user's Kerberos realm who have explicitly requested -such via subscriptions. Default subscriptions and any additional -personal subscriptions will be entered for the user. -.TP -.I net-visible -The user is registered with Zephyr. User location information is -retained by Zephyr and made available to any authenticated user who -requests such. Login and logout announcements will be sent only to users -within the user's Kerberos realm who have explicitly requested such via -subscriptions. Default subscriptions and any additional personal -subscriptions will be entered for the user. -.TP -.I net-announced -The user is registered with Zephyr. User location information is retained by -Zephyr and made available to any authenticated user who requests such. Login -and logout announcements will be sent to any user has requested such. -Default subscriptions and any additional personal -subscriptions will be entered for the user. -.SH EXAMPLES -.TP 25 -.B zctl -Runs \fIzctl\fR in interactive mode. -.TP -.B zctl load -Load subscriptions and un-subscriptions from \fI$HOME/.zephyr.subs\fR file. -.TP -.B zctl sub message personal -Subscribe to personal messages, but don't add this to the -subscriptions file. -.TP -.B zctl save -Save all current subscriptions to the default subscriptions file. -.TP -.B zctl set exposure none -Set your exposure level to `none', effectively turning off Zephyr. -.SH SEE ALSO -zephyr(1), zwgc(1), zhm(8), zephyrd(8) -gethostbyname(3) -.br -Project Athena Technical Plan Section E.4.1, `Zephyr Notification -Service' -.SH FILES -/tmp/wg.* -.br -$HOME/.zephyr.subs -.br -$ZEPHYR_VARS or $HOME/.zephyr.vars -.br -/etc/athena/zephyr.vars -.SH AUTHOR -.PP -Robert S. French (MIT-Project Athena) -.sp -.SH RESTRICTIONS -Copyright (c) 1987,1988 by the Massachusetts Institute of Technology. -All Rights Reserved. -.br -.I zephyr(1) -specifies the terms and conditions for redistribution. diff --git a/clients/zctl/zctl.1.in b/clients/zctl/zctl.1.in new file mode 100644 index 0000000..d3835d3 --- /dev/null +++ b/clients/zctl/zctl.1.in @@ -0,0 +1,311 @@ +.\" $Id$ +.\" +.\" Copyright 1987,1988 by the Massachusetts Institute of Technology +.\" All rights reserved. The file /usr/include/zephyr/mit-copyright.h +.\" specifies the terms and conditions for redistribution. +.\" +.\" +.TH ZCTL 1 "July 1, 1988" "MIT Project Athena" +.ds ]W MIT Project Athena +.SH NAME +zctl \- zephyr control program +.SH SYNOPSIS +.B zctl +[ +.I options +] +.SH DESCRIPTION +.I Zctl +is a general purpose control program for the +.I Zephyr(1) +Notification Service. It allows the user to subscribe to specific +notice types, to save the subscriptions in a file (default +$HOME/.zephyr.subs), to change his location information, and to send +control messages to the HostManager, +.I zhm(8), +and the WindowGram client, +.I zwgc(1). +.PP +The commands may be typed on the command line, or may be entered +interactively by just typing +.I zctl +and then typing commands to the prompt. +.br +.B NOTE: +For all commands accepting an optional \fIrecipient\fR argument, the +\fIrecipient\fR defaults to your Kerberos principal. You may also +subscribe to recipient ``\fI*\fR''. If you specify a recipient, it is +silently converted to ``\fI*\fR''. +.br +The commands are as follows: +.TP 15 +.B add \fIclass instance\fR [ \fIrecipient\fR ] +Subscribe to \fIclass, instance, recipient\fR, and add this triplet to +the subscriptions file. +.TP +.B add_unsubscription \fIclass instance\fR [ \fIrecipient\fR ] +Unsubscribe to \fIclass, instance, recipient\fR, and add this triplet +to the subscriptions file as an un-subscription. +For an explanation of un-subscriptions, see below. +.TP +.B cancel +Cancel all subscriptions. +.TP +.B defaults +Retrieve the default subscription list from the Zephyr server. +.TP +.B delete \fIclass instance\fR [ \fIrecipient\fR ] +Unsubscribe to \fIclass, instance, recipient\fR, and remove this triplet +from the subscriptions file. +.TP +.B delete_unsubscription \fIclass instance\fR [ \fIrecipient\fR ] +Unsubscribe to \fIclass, instance, recipient\fR, and remove this triplet +from the subscriptions file as an un-subscription. +.TP +.B file \fR[ \fIfile\fR ] +Set default subscriptions file to \fIfile\fR. If \fIfile\fR isn't specified, +show what the current subscriptions file is. +.TP +.B flush_locs +Tell the Zephyr servers to flush all location information associated with +the user. This should only be used to remove any incorrect data that may have +been left after a system crash. +.TP +.B hide +Hide your location as maintained by the Zephyr server. This does not +affect the value of the exposure variable (see below, under +.B set). +.TP +.B hm_flush +Tell the HostManager, +.I zhm(8), +to ask the server to flush all state associated with the current host. +.TP +.B list \fR[ \fIfile\fR ] +List contents of current subscriptions file or +.I file. +Any macros in the file (see below) are displayed verbatim and not expanded. +.TP +.B list_requests +List all available commands. May be abbreviated by '?'. +.TP +.B load \fR[ \fIfile\fR ] +Subscribe to all subscription triplets and unsubscribe to all +un-subscription triplets in current subscriptions file or \fIfile\fR. +.TP +.B new_server +Tell the HostManager, +.I zhm(8), +to find a new Zephyr server. +.TP +.B quit +Exit from \fIzctl. +.TP +.B retrieve +Retrieve all current subscriptions from the Zephyr server. These include +subscriptions that might have been made by other programs, such as +.I znol(1). +.TP +.B save \fR[ \fIfile\fR ] +Save all current subscriptions (as returned by the Zephyr server) +into current subscriptions file or \fIfile\fR. The +file will be replaced. +.TP +.B set \fIvar\fR [ \fIvalue\fR ] +Set the value of Zephyr variable \fIvar\fR to \fIvalue\fR, or null if +no \fIvalue\fR is specified. The variable \fBexposure\fR has special +significance, and can only be set to the values none, opstaff, realm-visible, +realm-announced, net-visible, and net-announced. Setting this variable +immediately updates the information in the Zephyr servers (see below for +an explanation of the exposure levels). In addition, +setting this variable to none automatically performs the equivalent of a +.B wg_shutdown +command, and setting it to one of the other values automatically +performs the equivalent of a +.B wg_startup +command. +.br +The variable \fBresolved_addresses\fR determines whether zwgc will, +for an IP address indicating the origin of a message, attempt to look +up the hostname corresponding to that IP address. The value none +indicates that hostnames will never be found, and that the zwgc +fromhost variable will thus always contain an IP address (in +dotted-decimal form). The value all indicates that there will always +be an attempt to look up a hostname. Note that in this case, if you +have any subscriptions with recipient ``\fI*\fR'', these subscriptions +may be revealed to other Zephyr users who operate their own DNS name +servers. Any other value is interpreted as a regular expression; +hostname lookup attempts will occur only if the IP address matches +this regular expression. +.br +Any variable settings you make will be stored in \fI$HOME/.zephyr.vars\fR +.TP +.B show \fIvar\fR [ \fIvar\fR \ ... ] +Show the value of the specified Zephyr variables. If a variable is not +defined in the user's own variables file, the system variables file +(\fI@sysconfdir@/zephyr/zephyr.vars\fR) is searched for a default value. +.TP +.B subscribe \fIclass instance\fR [ \fIrecipient\fR ] +Subscribe to \fIclass, instance, recipient\fR, but don't add this triplet to +the subscriptions file. +.TP +.B unhide +Make your location as maintained by the Zephyr server visible. This does not +affect the value of the exposure variable. +.TP +.B unload \fR[ \fIfile\fR ] +Unsubscribe to all subscription triplets in current subscriptions file +or \fIfile\fR. Un-subscriptions in the file are ignored. +.TP +.B unset \fIvar\fR [ \fIvar\fR \ ... ] +Delete the definitions of the specified Zephyr variables. +.TP +.B unsubscribe \fIclass instance\fR [ \fIrecipient\fR ] +Unsubscribe to \fIclass, instance, recipient\fR, but don't remove this triplet +from the subscriptions file. +.TP +.B wg_exit +Tell the WindowGram client, +.I zwgc(1), +to exit. +.TP +.B wg_read +Tell the WindowGram client, +.I zwgc(1), +to reread its description file. +.TP +.B wg_shutdown +Tell the WindowGram client to shutdown; this causes it to ignore all +notices until a wg_startup command is issued. +.TP +.B wg_startup +Tell the WindowGram client to start accepting notices again; useful +after a wg_shutdown command has been issued. +.SH MACROS and SUBSCRIPTION FILES +There are three macros, +.I %host%, %canon%, \fRand\fI %me%. %host% +is converted to the current hostname, \fI%canon%\fR is converted to the +official hostname as returned by +.I gethostbyname(3), +and \fI%me%\fR is converted to your Kerberos principal. These macros can be +used in your \fI$HOME/.zephyr.subs\fR file or as arguments to commands +to specify the +.I class +or +.I instance +fields. A sample \fI$HOME/.zephyr.subs\fR file might contain the following: +.PP +.nf + message,urgent,%me% + syslog,%host%,* + mail,pop,%me% +.fi +.PP +.I Zctl +reads the environment variable \fBWGFILE\fR, to find the name of the +file where the windowgram port resides. If \fBWGFILE\fR is not set, +the file name defaults to /tmp/wg.\fIuid\fR, where \fIuid\fR is the +user's UNIX uid. +.SH UN-SUBSCRIPTIONS +The zephyr server, +.I zephyrd(8), +maintains default subscriptions which are automatically added to all +users' subscriptions at the time of their first subscription during a +login session. If you wish to automatically remove some of these +default subscriptions, you use +.B un-subscriptions. +When you +.B load +a subscription file containing +un-subscriptions, the un-subscriptions are automatically sent to the +server as if you had used the +.B unsubscribe +command. +.SH EXPOSURE LEVELS +The different exposure levels affect the operation of zephyr and its +interaction with the user, as follows: +.TP 10 +.I none +This completely disables Zephyr for the user. The user is not +registered with Zephyr. No user location information is +retained by Zephyr. No login or logout announcements will be +sent. No subscriptions will be entered for the user, and no notices +will be displayed by +.I zwgc(1). +.TP +.I opstaff +The user is registered with Zephyr. No login or logout +announcements will be sent, and location information will only be +visible to Operations staff. Default subscriptions and any additional +personal subscriptions will be entered for the user. +.TP +.I realm-visible +The user is registered with Zephyr. User location information is retained by +Zephyr and made available only to users within the user's +Kerberos realm. No login or logout announcements will be sent. This +is the system default. Default subscriptions and any additional +personal subscriptions will be entered for the user. +.TP +.I realm-announced +The user is registered with Zephyr. User location information is retained by +Zephyr and made available only to users authenticated within the user's +Kerberos realm. Login and logout announcements will be sent, but only to +users within the user's Kerberos realm who have explicitly requested +such via subscriptions. Default subscriptions and any additional +personal subscriptions will be entered for the user. +.TP +.I net-visible +The user is registered with Zephyr. User location information is +retained by Zephyr and made available to any authenticated user who +requests such. Login and logout announcements will be sent only to users +within the user's Kerberos realm who have explicitly requested such via +subscriptions. Default subscriptions and any additional personal +subscriptions will be entered for the user. +.TP +.I net-announced +The user is registered with Zephyr. User location information is retained by +Zephyr and made available to any authenticated user who requests such. Login +and logout announcements will be sent to any user has requested such. +Default subscriptions and any additional personal +subscriptions will be entered for the user. +.SH EXAMPLES +.TP 25 +.B zctl +Runs \fIzctl\fR in interactive mode. +.TP +.B zctl load +Load subscriptions and un-subscriptions from \fI$HOME/.zephyr.subs\fR file. +.TP +.B zctl sub message personal +Subscribe to personal messages, but don't add this to the +subscriptions file. +.TP +.B zctl save +Save all current subscriptions to the default subscriptions file. +.TP +.B zctl set exposure none +Set your exposure level to `none', effectively turning off Zephyr. +.SH SEE ALSO +zephyr(1), zwgc(1), zhm(8), zephyrd(8) +gethostbyname(3) +.br +Project Athena Technical Plan Section E.4.1, `Zephyr Notification +Service' +.SH FILES +/tmp/wg.* +.br +$HOME/.zephyr.subs +.br +$ZEPHYR_VARS or $HOME/.zephyr.vars +.br +@sysconfdir@/zephyr/zephyr.vars +.SH AUTHOR +.PP +Robert S. French (MIT-Project Athena) +.sp +.SH RESTRICTIONS +Copyright (c) 1987,1988 by the Massachusetts Institute of Technology. +All Rights Reserved. +.br +.I zephyr(1) +specifies the terms and conditions for redistribution. -- cgit v1.2.3