citadel/utils.txt

   1                         Citadel/UX Utilities Manual
   2                  See copyright.doc for copyright information
   3
   4
   5  OVERVIEW
   6
   7    The following utilities will be discussed in this document:
   8  aidepost   Post standard input to the Aide> room. NOTE: called by chat.c
   9  whobbs     Who is on the system (connected to the server, actually.)
  10  msgstats   Print lowest & highest message numbers, and current file position
  11  stats      Print the calling statistics & graph.
  12  mailutil   Mailbox utilities
  13  msgform    Format a binary message to the screen (stdin or in a file)
  14  userlist   Print the userlist.
  15  readlog    Read the caller log
  16  useradmin  Full-screen user account editor. NOTE: requires the "curses" lib
  17  sysoputil  Various and sundry sysop utilities.
  18
  19    It is up to you to decide which utilities should be made accessible only
  20 to sysops. It is important that you set the file permissions correctly. All
  21 utilities should have access to the BBS data files, whether through ownership
  22 or set-user-id. In addition, aidepost should be accessible by the chat program,
  23 and userlist & whobbs should be accessible by citadel. I will attempt to
  24 address each program individually.
  25
  26
  27   AIDEPOST
  28
  29    The nature of this program is rather simple. Standard input (stdin) is
  30 converted into a message, filed in the main message file (msgmain), and posted
  31 in the Aide> room. This is useful for keeping transcripts of system activity
  32 that has to do with the BBS. You may also wish to have a really BIG msgmain
  33 file, and have all of your normal system logs go in there also.
  34
  35
  36   WHOBBS
  37
  38    This program is similar to the "who" command.  It lists all of the users
  39 who are currently connected to your BBS server, either locally or across a
  40 network.  Unless you're running a standalone system, "who" and "whobbs" will
  41 probably not have a one-to-one correspondence (unlike earlier versions of the
  42 system).
  43
  44    One thing to keep in mind is that the "whobbs" utility actually opens a
  45 connection to the server.  If the server is maxed out, whobbs will still be
  46 able to provide a listing, because it doesn't need to log in to execute the
  47 RWHO command.  Note that whobbs does not list its own session.
  48
  49    Running the <W>ho is online command from the client does *not* call this
  50 utility.  It has this functionality built in.
  51
  52
  53   MSGSTATS
  54
  55    This program displays the lowest and highest message numbers which currently
  56 exist in the master file, the current file pointer (what byte in msgmain the
  57 next message entered will start at), and whether the file is locked or
  58 unlocked. Normally the file will only be locked for a second or two during a
  59 message <S>ave, or network processing, but if there is a glitch somewhere and
  60 the file remains locked, this program will tell you so and you can use the
  61 unlock option in sysoputil.
  62
  63    As of release 3.23, message base locking is a lot more reliable, because
  64 it uses file-locking system calls if they are available.  But, if you're
  65 running on a brain-damaged kernel that doesn't have file locking, and your
  66 message base appears to be locked up, this will tell you.
  67
  68    This utility now also provides information on the total number of
  69 messages currently on the system, and the average message length.
  70
  71
  72   STATS
  73
  74    (NOTE: this program no longer uses the "curses" library.)   It prints
  75 various statistics on the screen based on the calllog file, such as number
  76 of connects, number of logins, number of logouts, number of disconnects,
  77 bad password attempts, etc. All statistics are provided in three figures:
  78 times per call, times per day, and total times.
  79    After this screen appears, you may press return for the next screen. This
  80 is a graphic representation of system usage, broken down into 20 minute
  81 segments of the day.  This will show you when your peak usage is.
  82    Press return again and the stats program will list your system's top
  83 20 callers.
  84    The final screen lists the twenty users with the highest post per call
  85 ratios.  Unline the other screens, this statistic is extracted from the user
  86 file itself rather than the call log.
  87
  88  stats may be called with the "-b" option to run in batch mode.  In this case,
  89 it skips all the prompts and just prints everything out in one bulk output.
  90 Or it may be called with the "-p" option to only print the Post-to-Call
  91 ratios and nothing else.
  92
  93
  94   MAILUTIL
  95
  96     This utility allows you to perform various operations on a user's
  97 mailbox.  Note that reading people's mail is, of course, unethical, and
  98 possibly illegal.
  99
 100   MSGFORM
 101
 102    On occasion, I have had messages in Citadel/UX binary format that I have
 103 wanted to view. Or needed a way to view a network spool file. Or wanted to
 104 directly examine parts of msgmain. This program is a simple message formatter.
 105    msgform reads standard input, scanning for binary messages, starting
 106 with an <FF> byte and ending after the final NULL, and print as many as it
 107 finds until it encounters EOF.
 108    You could use this utility along with netproc to provide printouts or
 109 archives of certain rooms.
 110
 111
 112   USERLIST
 113
 114    This is a program to print the userlist. There are two flags that may be
 115 set when running this program. When called without any arguments, userlist
 116 will display all users (except those who have chosen to be unlisted), their
 117 user numbers, times called, messages posted, screen width, and date of their
 118 most recent call.
 119
 120    Setting the -p option (only allowed by root as distributed; you may wish
 121 to change this) also displays passwords, and lists all users regardless of
 122 whether they are unlisted.
 123
 124    Setting the -n option causes the next argument after -n to be a user
 125 number to search for.
 126
 127    You can also elect to sort the output by user name or user number by
 128 specifying the -su or -sn flags.
 129
 130
 131   READLOG
 132
 133    Called without any arguments, readlog dumps the contents of the calllog
 134 file. This file records all times the Citadel/UX program has been started, and
 135 at what baud rate, as well as logins, proper logouts, loss of carrier (SIGHUP),
 136 bad password attempts, and new user logins.
 137    Readlog called with the -t argument displays a list of the names of the
 138 last twenty users who have logged in.
 139
 140
 141   USERADMIN
 142
 143    Useradmin is a full-screen program to view and edit any user's account.
 144 The program will prompt for a user name. After you enter the name, various
 145 parameters of the user's account will appear on the screen. To change one
 146 of the parameters, simply enter its number.
 147
 148   1. User name - you may change a user's name at any time.  If you do this,
 149 the hash table to the user file will be rewritten when you exit useradmin.
 150   2. User number - if you change a user's number, keep in mind that the user's
 151 account will no longer be attached to any other records which are indexed by
 152 user number, such as registration, room aide assignments, etc.  These must be
 153 changed as well.
 154   3. UID attachment - if you wish to attach a BBS account to an /etc/passwd
 155 account, simply make the uid's the same. Likewise, if a user is to no longer
 156 have an account in /etc/passwd, simply set this to the same as BBSUID. Note
 157 that the user's "full name" in /etc/passwd MUST be the same as their BBS login
 158 name, otherwise a new (and probably unwanted) account will be created.
 159   4. Password          - these four fields are self explanatory.
 160   5. Screen width
 161   6. Times called
 162   7. Messages posted
 163   8. Last call - Date and time of last call. If you select this,
 164 it will not prompt for a new time, but set it to the current time.
 165   9. Access Level - choose from the standard access levels:
 166        0 = Marked for deletion
 167        1 = New unvalidated user
 168        2 = Problem user
 169        3 = Validated user without network privileges
 170        4 = Validated user with network privileges
 171        5 = Preferred user
 172        6 = Aide
 173
 174   The rest are boolean flags. Selecting them will toggle the options.
 175  10. Permanent user (do not scroll off)
 176  11. Print last old message on new message request
 177  12. Expert mode (supress automatic hints)
 178  13. Do not list in .RU command
 179  14. Prompting after each message
 180  15. Registered in the registration file
 181  16. Pause after each screenful of text
 182
 183   In addition, if the user is registered, you can type -1 to make the
 184 corresponding record in the registration file appear on the screen.
 185    When you are finished examining or editing an account, type 0 to exit. It
 186 will ask you if you wish to save the changes.
 187
 188
 189   SYSOPUTIL
 190
 191    This program handles some of the sysop functions of the system. It can
 192 be called three ways: sysoputil by itself brings up the menu. Also:
 193  sysoputil -u      Execute option 7 (user purge) and exit
 194  sysoputil -r      Execute option 1 (room purge) and exit
 195  sysoputil -g      Execute option 2 (registration list) and exit
 196  sysoputil -h      Execute option 3 (rewrite hash table) and exit
 197
 198   The menu choices are as follows:
 199
 200   1. Purge old rooms. This will delete any rooms which have not been written
 201 to (posted in) in two weeks. Notification of purged rooms is posted in the
 202 Aide> room (using the aidepost utility).
 203  2. Read registration file. This will partially list the registration file
 204 to the screen (partially: street address is omitted).
 205  3. Rewrite hash table.  Under normal conditions, the hash table of user
 206 names is updated whenever usersupp is updated.  If the system for some
 207 reason doesn't know about any users, but they're right there for you to see
 208 when you run userlist, chances are the hash table is out of sync.  This will
 209 hardly ever happen unless the disk was full, or you've been tinkering with
 210 usersupp, or if you're upgrading from a non-hashing version of Citadel.  This
 211 option will rewrite the hash table from scratch.
 212  4. Unlock message file. The msgmain file is locked during message saves to
 213 prevent two users from writing to the file at once. If there is some sort of
 214 crash or bug and it remains locked, this will unlock it.
 215  5. Sort the userlog by user ID.
 216  6. Sort the userlog by user name.  (Sorting the userlog is a purely cosmetic
 217 option, and will not at all affect the performance of the system.)
 218  7. Purge old users. This will delete any users which have not called in
 219 two months. Notification of purged users is posted in the Aide> room (using
 220 the aidepost utility).
 221  9. Quit
 222
 223
 224    That should cover all of the included utilities. Comments, suggestions,
 225 etc. may be sent to ajc@uncnsrd.mt-kisco.ny.us or call UNCENSORED! BBS at
 226 (914) 244-3252 (modem) or uncnsrd.mt-kisco.ny.us (Internet).