zephyr/clients/zctl/zctl.1

   1 .\"     $Id: zctl.1,v 1.12 1999/01/22 23:18:29 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 Any variable settings you make will be stored in \fI$HOME/.zephyr.vars\fR
 129 .TP
 130 .B show \fIvar\fR [ \fIvar\fR \ ... ]
 131 Show the value of the specified Zephyr variables.  If a variable is not
 132 defined in the user's own variables file, the system variables file
 133 (\fI/etc/athena/zephyr.vars\fR) is searched for a default value.
 134 .TP
 135 .B subscribe \fIclass instance\fR [ \fIrecipient\fR ]
 136 Subscribe to \fIclass, instance, recipient\fR, but don't add this triplet to
 137 the subscriptions file.
 138 .TP
 139 .B unhide
 140 Make your location as maintained by the Zephyr server visible.  This does not
 141 affect the value of the exposure variable.
 142 .TP
 143 .B unload \fR[ \fIfile\fR ]
 144 Unsubscribe to all subscription triplets in current subscriptions file
 145 or \fIfile\fR.  Un-subscriptions in the file are ignored.
 146 .TP
 147 .B unset \fIvar\fR [ \fIvar\fR \ ... ]
 148 Delete the definitions of the specified Zephyr variables.
 149 .TP
 150 .B unsubscribe \fIclass instance\fR [ \fIrecipient\fR ]
 151 Unsubscribe to \fIclass, instance, recipient\fR, but don't remove this triplet
 152 from the subscriptions file.
 153 .TP
 154 .B wg_exit
 155 Tell the WindowGram client,
 156 .I zwgc(1),
 157 to exit.
 158 .TP
 159 .B wg_read
 160 Tell the WindowGram client,
 161 .I zwgc(1),
 162 to reread its description file.
 163 .TP
 164 .B wg_shutdown
 165 Tell the WindowGram client to shutdown; this causes it to ignore all
 166 notices until a wg_startup command is issued.
 167 .TP
 168 .B wg_startup
 169 Tell the WindowGram client to start accepting notices again; useful
 170 after a wg_shutdown command has been issued.
 171 .SH MACROS and SUBSCRIPTION FILES
 172 There are three macros,
 173 .I %host%, %canon%, \fRand\fI %me%.  %host%
 174 is converted to the current hostname, \fI%canon%\fR is converted to the
 175 official hostname as returned by
 176 .I gethostbyname(3),
 177 and \fI%me%\fR is converted to your Kerberos principal.  These macros can be
 178 used in your \fI$HOME/.zephyr.subs\fR file or as arguments to commands
 179 to specify the
 180 .I class
 181 or
 182 .I instance
 183 fields.  A sample \fI$HOME/.zephyr.subs\fR file might contain the following:
 184 .PP
 185 .nf
 186         message,urgent,%me%
 187         syslog,%host%,*
 188         mail,pop,%me%
 189 .fi
 190 .PP
 191 .I Zctl
 192 reads the environment variable \fBWGFILE\fR, to find the name of the
 193 file where the windowgram port resides.  If \fBWGFILE\fR is not set,
 194 the file name defaults to /tmp/wg.\fIuid\fR, where \fIuid\fR is the
 195 user's UNIX uid.
 196 .SH UN-SUBSCRIPTIONS
 197 The zephyr server,
 198 .I zephyrd(8),
 199 maintains default subscriptions which are automatically added to all
 200 users' subscriptions at the time of their first subscription during a
 201 login session.  If you wish to automatically remove some of these
 202 default subscriptions, you use
 203 .B un-subscriptions.
 204 When you
 205 .B load
 206 a subscription file containing
 207 un-subscriptions, the un-subscriptions are automatically sent to the
 208 server as if you had used the
 209 .B unsubscribe
 210 command.
 211 .SH EXPOSURE LEVELS
 212 The different exposure levels affect the operation of zephyr and its
 213 interaction with the user, as follows:
 214 .TP 10
 215 .I none
 216 This completely disables Zephyr for the user. The user is not
 217 registered with Zephyr.  No user location information is
 218 retained by Zephyr.  No login or logout announcements will be
 219 sent.  No subscriptions will be entered for the user, and no notices
 220 will be displayed by
 221 .I zwgc(1).
 222 .TP
 223 .I opstaff
 224 The user is registered with Zephyr.  No login or logout
 225 announcements will be sent, and location information will only be
 226 visible to Operations staff.  Default subscriptions and any additional
 227 personal subscriptions will be entered for the user.
 228 .TP
 229 .I realm-visible
 230 The user is registered with Zephyr.  User location information is retained by
 231 Zephyr and made available only to users within the user's
 232 Kerberos realm.  No login or logout announcements will be sent.  This
 233 is the system default.  Default subscriptions and any additional
 234 personal subscriptions will be entered for the user.
 235 .TP
 236 .I realm-announced
 237 The user is registered with Zephyr.  User location information is retained by
 238 Zephyr and made available only to users authenticated within the user's
 239 Kerberos realm.  Login and logout announcements will be sent, but only to
 240 users within the user's Kerberos realm who have explicitly requested
 241 such via subscriptions.  Default subscriptions and any additional
 242 personal subscriptions will be entered for the user.
 243 .TP
 244 .I net-visible
 245 The user is registered with Zephyr.  User location information is
 246 retained by Zephyr and made available to any authenticated user who
 247 requests such. Login and logout announcements will be sent only to users
 248 within the user's Kerberos realm who have explicitly requested such via
 249 subscriptions.  Default subscriptions and any additional personal
 250 subscriptions will be entered for the user.
 251 .TP
 252 .I net-announced
 253 The user is registered with Zephyr. User location information is retained by
 254 Zephyr and made available to any authenticated user who requests such.  Login
 255 and logout announcements will be sent to any user has requested such.
 256 Default subscriptions and any additional personal
 257 subscriptions will be entered for the user.
 258 .SH EXAMPLES
 259 .TP 25
 260 .B zctl
 261 Runs \fIzctl\fR in interactive mode.
 262 .TP
 263 .B zctl load
 264 Load subscriptions and un-subscriptions from \fI$HOME/.zephyr.subs\fR file.
 265 .TP
 266 .B zctl sub message personal
 267 Subscribe to personal messages, but don't add this to the
 268 subscriptions file.
 269 .TP
 270 .B zctl save
 271 Save all current subscriptions to the default subscriptions file.
 272 .TP
 273 .B zctl set exposure none
 274 Set your exposure level to `none', effectively turning off Zephyr.
 275 .SH SEE ALSO
 276 zephyr(1), zwgc(1), zhm(8), zephyrd(8)
 277 gethostbyname(3)
 278 .br
 279 Project Athena Technical Plan Section E.4.1, `Zephyr Notification
 280 Service'
 281 .SH FILES
 282 /tmp/wg.*
 283 .br
 284 $HOME/.zephyr.subs
 285 .br
 286 $HOME/.zephyr.vars
 287 .br
 288 /etc/athena/zephyr.vars
 289 .SH AUTHOR
 290 .PP
 291 Robert S. French (MIT-Project Athena)
 292 .sp
 293 .SH RESTRICTIONS
 294 Copyright (c) 1987,1988 by the Massachusetts Institute of Technology.
 295 All Rights Reserved.
 296 .br
 297 .I zephyr(1)
 298 specifies the terms and conditions for redistribution.