zephyr/clients/zctl/zctl.1

   1 .\"     $Id: zctl.1,v 1.13 2000/08/10 15:12:56 ghudson Exp $
   2 .\"
   3 .\" Copyright 1987,1988 by the Massachusetts Institute of Technology
   4 .\" All rights reserved.  The file /usr/include/zephyr/mit-copyright.h
   5 .\" specifies the terms and conditions for redistribution.
   6 .\"
   7 .\"
   8 .TH ZCTL 1 "July 1, 1988" "MIT Project Athena"
   9 .ds ]W MIT Project Athena
  10 .SH NAME
  11 zctl \- zephyr control program
  12 .SH SYNOPSIS
  13 .B zctl
  14 [
  15 .I options
  16 ]
  17 .SH DESCRIPTION
  18 .I Zctl
  19 is a general purpose control program for the
  20 .I Zephyr(1)
  21 Notification Service.  It allows the user to subscribe to specific
  22 notice types, to save the subscriptions in a file (default
  23 $HOME/.zephyr.subs), to change his location information, and to send
  24 control messages to the HostManager,
  25 .I zhm(8),
  26 and the WindowGram client,
  27 .I zwgc(1).
  28 .PP
  29 The commands may be typed on the command line, or may be entered
  30 interactively by just typing
  31 .I zctl
  32 and then typing commands to the prompt.
  33 .br
  34 .B NOTE:
  35 For all commands accepting an optional \fIrecipient\fR argument, the
  36 \fIrecipient\fR defaults to your Kerberos principal.  You may also
  37 subscribe to recipient ``\fI*\fR''.  If you specify a recipient, it is
  38 silently converted to ``\fI*\fR''.
  39 .br
  40 The commands are as follows:
  41 .TP 15
  42 .B add \fIclass instance\fR [ \fIrecipient\fR ]
  43 Subscribe to \fIclass, instance, recipient\fR, and add this triplet to
  44 the subscriptions file.
  45 .TP
  46 .B add_unsubscription \fIclass instance\fR [ \fIrecipient\fR ]
  47 Unsubscribe to \fIclass, instance, recipient\fR, and add this triplet
  48 to the subscriptions file as an un-subscription.
  49 For an explanation of un-subscriptions, see below.
  50 .TP
  51 .B cancel
  52 Cancel all subscriptions.
  53 .TP
  54 .B defaults
  55 Retrieve the default subscription list from the Zephyr server.
  56 .TP
  57 .B delete \fIclass instance\fR [ \fIrecipient\fR ]
  58 Unsubscribe to \fIclass, instance, recipient\fR, and remove this triplet
  59 from the subscriptions file.
  60 .TP
  61 .B delete_unsubscription \fIclass instance\fR [ \fIrecipient\fR ]
  62 Unsubscribe to \fIclass, instance, recipient\fR, and remove this triplet
  63 from the subscriptions file as an un-subscription.
  64 .TP
  65 .B file \fR[ \fIfile\fR ]
  66 Set default subscriptions file to \fIfile\fR.  If \fIfile\fR isn't specified,
  67 show what the current subscriptions file is.
  68 .TP
  69 .B flush_locs
  70 Tell the Zephyr servers to flush all location information associated with
  71 the user.  This should only be used to remove any incorrect data that may have
  72 been left after a system crash.
  73 .TP
  74 .B hide
  75 Hide your location as maintained by the Zephyr server.  This does not
  76 affect the value of the exposure variable (see below, under
  77 .B set).
  78 .TP
  79 .B hm_flush
  80 Tell the HostManager,
  81 .I zhm(8),
  82 to ask the server to flush all state associated with the current host.
  83 .TP
  84 .B list \fR[ \fIfile\fR ]
  85 List contents of current subscriptions file or
  86 .I file.
  87 Any macros in the file (see below) are displayed verbatim and not expanded.
  88 .TP
  89 .B list_requests
  90 List all available commands.  May be abbreviated by '?'.
  91 .TP
  92 .B load \fR[ \fIfile\fR ]
  93 Subscribe to all subscription triplets and unsubscribe to all
  94 un-subscription triplets in current subscriptions file or \fIfile\fR.
  95 .TP
  96 .B new_server
  97 Tell the HostManager,
  98 .I zhm(8),
  99 to find a new Zephyr server.
 100 .TP
 101 .B quit
 102 Exit from \fIzctl.
 103 .TP
 104 .B retrieve
 105 Retrieve all current subscriptions from the Zephyr server.  These include
 106 subscriptions that might have been made by other programs, such as
 107 .I znol(1).
 108 .TP
 109 .B save \fR[ \fIfile\fR ]
 110 Save all current subscriptions (as returned by the Zephyr server)
 111 into current subscriptions file or \fIfile\fR.  The
 112 file will be replaced.
 113 .TP
 114 .B set \fIvar\fR [ \fIvalue\fR ]
 115 Set the value of Zephyr variable \fIvar\fR to \fIvalue\fR, or null if
 116 no \fIvalue\fR is specified.  The variable \fBexposure\fR has special
 117 significance, and can only be set to the values none, opstaff, realm-visible,
 118 realm-announced, net-visible, and net-announced.  Setting this variable
 119 immediately updates the information in the Zephyr servers (see below for
 120 an explanation of the exposure levels).  In addition,
 121 setting this variable to none automatically performs the equivalent of a
 122 .B wg_shutdown
 123 command, and setting it to one of the other values automatically
 124 performs the equivalent of a
 125 .B wg_startup
 126 command.
 127 .br
 128 The variable \fBresolved_addresses\fR determines whether zwgc will,
 129 for an IP address indicating the origin of a message, attempt to look
 130 up the hostname corresponding to that IP address. The value none
 131 indicates that hostnames will never be found, and that the zwgc
 132 fromhost variable will thus always contain an IP address (in
 133 dotted-decimal form). The value all indicates that there will always
 134 be an attempt to look up a hostname. Note that in this case, if you
 135 have any subscriptions with recipient ``\fI*\fR'', these subscriptions
 136 may be revealed to other Zephyr users who operate their own DNS name
 137 servers. Any other value is interpreted as a regular expression;
 138 hostname lookup attempts will occur only if the IP address matches
 139 this regular expression.
 140 .br
 141 Any variable settings you make will be stored in \fI$HOME/.zephyr.vars\fR
 142 .TP
 143 .B show \fIvar\fR [ \fIvar\fR \ ... ]
 144 Show the value of the specified Zephyr variables.  If a variable is not
 145 defined in the user's own variables file, the system variables file
 146 (\fI/etc/athena/zephyr.vars\fR) is searched for a default value.
 147 .TP
 148 .B subscribe \fIclass instance\fR [ \fIrecipient\fR ]
 149 Subscribe to \fIclass, instance, recipient\fR, but don't add this triplet to
 150 the subscriptions file.
 151 .TP
 152 .B unhide
 153 Make your location as maintained by the Zephyr server visible.  This does not
 154 affect the value of the exposure variable.
 155 .TP
 156 .B unload \fR[ \fIfile\fR ]
 157 Unsubscribe to all subscription triplets in current subscriptions file
 158 or \fIfile\fR.  Un-subscriptions in the file are ignored.
 159 .TP
 160 .B unset \fIvar\fR [ \fIvar\fR \ ... ]
 161 Delete the definitions of the specified Zephyr variables.
 162 .TP
 163 .B unsubscribe \fIclass instance\fR [ \fIrecipient\fR ]
 164 Unsubscribe to \fIclass, instance, recipient\fR, but don't remove this triplet
 165 from the subscriptions file.
 166 .TP
 167 .B wg_exit
 168 Tell the WindowGram client,
 169 .I zwgc(1),
 170 to exit.
 171 .TP
 172 .B wg_read
 173 Tell the WindowGram client,
 174 .I zwgc(1),
 175 to reread its description file.
 176 .TP
 177 .B wg_shutdown
 178 Tell the WindowGram client to shutdown; this causes it to ignore all
 179 notices until a wg_startup command is issued.
 180 .TP
 181 .B wg_startup
 182 Tell the WindowGram client to start accepting notices again; useful
 183 after a wg_shutdown command has been issued.
 184 .SH MACROS and SUBSCRIPTION FILES
 185 There are three macros,
 186 .I %host%, %canon%, \fRand\fI %me%.  %host%
 187 is converted to the current hostname, \fI%canon%\fR is converted to the
 188 official hostname as returned by
 189 .I gethostbyname(3),
 190 and \fI%me%\fR is converted to your Kerberos principal.  These macros can be
 191 used in your \fI$HOME/.zephyr.subs\fR file or as arguments to commands
 192 to specify the
 193 .I class
 194 or
 195 .I instance
 196 fields.  A sample \fI$HOME/.zephyr.subs\fR file might contain the following:
 197 .PP
 198 .nf
 199         message,urgent,%me%
 200         syslog,%host%,*
 201         mail,pop,%me%
 202 .fi
 203 .PP
 204 .I Zctl
 205 reads the environment variable \fBWGFILE\fR, to find the name of the
 206 file where the windowgram port resides.  If \fBWGFILE\fR is not set,
 207 the file name defaults to /tmp/wg.\fIuid\fR, where \fIuid\fR is the
 208 user's UNIX uid.
 209 .SH UN-SUBSCRIPTIONS
 210 The zephyr server,
 211 .I zephyrd(8),
 212 maintains default subscriptions which are automatically added to all
 213 users' subscriptions at the time of their first subscription during a
 214 login session.  If you wish to automatically remove some of these
 215 default subscriptions, you use
 216 .B un-subscriptions.
 217 When you
 218 .B load
 219 a subscription file containing
 220 un-subscriptions, the un-subscriptions are automatically sent to the
 221 server as if you had used the
 222 .B unsubscribe
 223 command.
 224 .SH EXPOSURE LEVELS
 225 The different exposure levels affect the operation of zephyr and its
 226 interaction with the user, as follows:
 227 .TP 10
 228 .I none
 229 This completely disables Zephyr for the user. The user is not
 230 registered with Zephyr.  No user location information is
 231 retained by Zephyr.  No login or logout announcements will be
 232 sent.  No subscriptions will be entered for the user, and no notices
 233 will be displayed by
 234 .I zwgc(1).
 235 .TP
 236 .I opstaff
 237 The user is registered with Zephyr.  No login or logout
 238 announcements will be sent, and location information will only be
 239 visible to Operations staff.  Default subscriptions and any additional
 240 personal subscriptions will be entered for the user.
 241 .TP
 242 .I realm-visible
 243 The user is registered with Zephyr.  User location information is retained by
 244 Zephyr and made available only to users within the user's
 245 Kerberos realm.  No login or logout announcements will be sent.  This
 246 is the system default.  Default subscriptions and any additional
 247 personal subscriptions will be entered for the user.
 248 .TP
 249 .I realm-announced
 250 The user is registered with Zephyr.  User location information is retained by
 251 Zephyr and made available only to users authenticated within the user's
 252 Kerberos realm.  Login and logout announcements will be sent, but only to
 253 users within the user's Kerberos realm who have explicitly requested
 254 such via subscriptions.  Default subscriptions and any additional
 255 personal subscriptions will be entered for the user.
 256 .TP
 257 .I net-visible
 258 The user is registered with Zephyr.  User location information is
 259 retained by Zephyr and made available to any authenticated user who
 260 requests such. Login and logout announcements will be sent only to users
 261 within the user's Kerberos realm who have explicitly requested such via
 262 subscriptions.  Default subscriptions and any additional personal
 263 subscriptions will be entered for the user.
 264 .TP
 265 .I net-announced
 266 The user is registered with Zephyr. User location information is retained by
 267 Zephyr and made available to any authenticated user who requests such.  Login
 268 and logout announcements will be sent to any user has requested such.
 269 Default subscriptions and any additional personal
 270 subscriptions will be entered for the user.
 271 .SH EXAMPLES
 272 .TP 25
 273 .B zctl
 274 Runs \fIzctl\fR in interactive mode.
 275 .TP
 276 .B zctl load
 277 Load subscriptions and un-subscriptions from \fI$HOME/.zephyr.subs\fR file.
 278 .TP
 279 .B zctl sub message personal
 280 Subscribe to personal messages, but don't add this to the
 281 subscriptions file.
 282 .TP
 283 .B zctl save
 284 Save all current subscriptions to the default subscriptions file.
 285 .TP
 286 .B zctl set exposure none
 287 Set your exposure level to `none', effectively turning off Zephyr.
 288 .SH SEE ALSO
 289 zephyr(1), zwgc(1), zhm(8), zephyrd(8)
 290 gethostbyname(3)
 291 .br
 292 Project Athena Technical Plan Section E.4.1, `Zephyr Notification
 293 Service'
 294 .SH FILES
 295 /tmp/wg.*
 296 .br
 297 $HOME/.zephyr.subs
 298 .br
 299 $HOME/.zephyr.vars
 300 .br
 301 /etc/athena/zephyr.vars
 302 .SH AUTHOR
 303 .PP
 304 Robert S. French (MIT-Project Athena)
 305 .sp
 306 .SH RESTRICTIONS
 307 Copyright (c) 1987,1988 by the Massachusetts Institute of Technology.
 308 All Rights Reserved.
 309 .br
 310 .I zephyr(1)
 311 specifies the terms and conditions for redistribution.