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  stats      Print the calling statistics & graph.
  11  msgform    Format a binary message to the screen (stdin or in a file)
  12  userlist   Print the userlist.
  13  readlog    Read the caller log
  14  useradmin  Full-screen user account editor. NOTE: requires the "curses" lib
  15  sysoputil  Various and sundry sysop utilities.
  16
  17    It is up to you to decide which utilities should be made accessible only
  18 to sysops. It is important that you set the file permissions correctly. All
  19 utilities should have access to the BBS data files, whether through ownership
  20 or set-user-id. In addition, aidepost should be accessible by the chat program,
  21 and userlist & whobbs should be accessible by citadel. I will attempt to
  22 address each program individually.
  23
  24
  25   AIDEPOST
  26
  27    The nature of this program is rather simple. Standard input (stdin) is
  28 converted into a message, filed in the main message file (msgmain), and posted
  29 in the Aide> room. This is useful for keeping transcripts of system activity
  30 that has to do with the BBS. You may also wish to have a really BIG msgmain
  31 file, and have all of your normal system logs go in there also.
  32
  33
  34   WHOBBS
  35
  36    This program is similar to the "who" command.  It lists all of the users
  37 who are currently connected to your BBS server, either locally or across a
  38 network.  Unless you're running a standalone system, "who" and "whobbs" will
  39 probably not have a one-to-one correspondence (unlike earlier versions of the
  40 system).
  41
  42    One thing to keep in mind is that the "whobbs" utility actually opens a
  43 connection to the server.  If the server is maxed out, whobbs will still be
  44 able to provide a listing, because it doesn't need to log in to execute the
  45 RWHO command.  Note that whobbs does not list its own session.
  46
  47    Running the <W>ho is online command from the client does *not* call this
  48 utility.  It has this functionality built in.
  49
  50
  51   STATS
  52
  53    (NOTE: this program no longer uses the "curses" library.)   It prints
  54 various statistics on the screen based on the calllog file, such as number
  55 of connects, number of logins, number of logouts, number of disconnects,
  56 bad password attempts, etc. All statistics are provided in three figures:
  57 times per call, times per day, and total times.
  58    After this screen appears, you may press return for the next screen. This
  59 is a graphic representation of system usage, broken down into 20 minute
  60 segments of the day.  This will show you when your peak usage is.
  61    Press return again and the stats program will list your system's top
  62 20 callers.
  63    The final screen lists the twenty users with the highest post per call
  64 ratios.  Unline the other screens, this statistic is extracted from the user
  65 file itself rather than the call log.
  66
  67  stats may be called with the "-b" option to run in batch mode.  In this case,
  68 it skips all the prompts and just prints everything out in one bulk output.
  69 Or it may be called with the "-p" option to only print the Post-to-Call
  70 ratios and nothing else.
  71
  72
  73   MSGFORM
  74
  75    On occasion, I have had messages in Citadel/UX binary format that I have
  76 wanted to view. Or needed a way to view a network spool file. Or wanted to
  77 directly examine parts of msgmain. This program is a simple message formatter.
  78    msgform reads standard input, scanning for binary messages, starting
  79 with an <FF> byte and ending after the final NULL, and print as many as it
  80 finds until it encounters EOF.
  81    You could use this utility along with netproc to provide printouts or
  82 archives of certain rooms.
  83
  84
  85   USERLIST
  86
  87    This is a program to print the userlist. There are two flags that may be
  88 set when running this program. When called without any arguments, userlist
  89 will display all users (except those who have chosen to be unlisted), their
  90 user numbers, times called, messages posted, screen width, and date of their
  91 most recent call.
  92
  93    userlist is simply the same user listing code that is in the client, made
  94 into a standalone utility for convenience.
  95
  96
  97   READLOG
  98
  99    Called without any arguments, readlog dumps the contents of the calllog
 100 file. This file records all times the Citadel/UX program has been started, and
 101 at what baud rate, as well as logins, proper logouts, loss of carrier (SIGHUP),
 102 bad password attempts, and new user logins.
 103
 104
 105   USERADMIN
 106
 107    Useradmin is a full-screen program to view and edit any user's account.
 108 The program will prompt for a user name. After you enter the name, various
 109 parameters of the user's account will appear on the screen. To change one
 110 of the parameters, simply enter its number.
 111
 112   1. User name - you may change a user's name at any time.  If you do this,
 113 the hash table to the user file will be rewritten when you exit useradmin.
 114   2. User number - if you change a user's number, keep in mind that the user's
 115 account will no longer be attached to any other records which are indexed by
 116 user number, such as registration, room aide assignments, etc.  These must be
 117 changed as well.
 118   3. UID attachment - if you wish to attach a BBS account to an /etc/passwd
 119 account, simply make the uid's the same. Likewise, if a user is to no longer
 120 have an account in /etc/passwd, simply set this to the same as BBSUID. Note
 121 that the user's "full name" in /etc/passwd MUST be the same as their BBS login
 122 name, otherwise a new (and probably unwanted) account will be created.
 123   4. Password          - these four fields are self explanatory.
 124   5. Screen width
 125   6. Times called
 126   7. Messages posted
 127   8. Last call - Date and time of last call. If you select this,
 128 it will not prompt for a new time, but set it to the current time.
 129   9. Access Level - choose from the standard access levels:
 130        0 = Marked for deletion
 131        1 = New unvalidated user
 132        2 = Problem user
 133        3 = Validated user without network privileges
 134        4 = Validated user with network privileges
 135        5 = Preferred user
 136        6 = Aide
 137
 138   The rest are boolean flags. Selecting them will toggle the options.
 139  10. Permanent user (do not scroll off)
 140  11. Print last old message on new message request
 141  12. Expert mode (supress automatic hints)
 142  13. Do not list in .RU command
 143  14. Prompting after each message
 144  15. Registered in the registration file
 145  16. Pause after each screenful of text
 146
 147   In addition, if the user is registered, you can type -1 to make the
 148 corresponding record in the registration file appear on the screen.
 149    When you are finished examining or editing an account, type 0 to exit. It
 150 will ask you if you wish to save the changes.
 151
 152
 153   SYSOPUTIL
 154
 155    This program handles some of the sysop functions of the system. It can
 156 be called three ways: sysoputil by itself brings up the menu. Also:
 157  sysoputil -u      Execute option 7 (user purge) and exit
 158  sysoputil -r      Execute option 1 (room purge) and exit
 159
 160   The menu choices are as follows:
 161
 162   1. Purge old rooms. This will delete any rooms which have not been written
 163 to (posted in) in two weeks. Notification of purged rooms is posted in the
 164 Aide> room (using the aidepost utility).
 165  7. Purge old users. This will delete any users which have not called in
 166 two months. Notification of purged users is posted in the Aide> room (using
 167 the aidepost utility).
 168  9. Quit
 169
 170
 171    That should cover all of the included utilities. Comments, suggestions,
 172 etc. may be sent to ajc@uncnsrd.mt-kisco.ny.us or call UNCENSORED! BBS at
 173 (914) 244-3252 (modem) or uncnsrd.mt-kisco.ny.us (Internet).