citadel/docs/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
   9  whobbs       Who is on the system
  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  sendcommand  Send a server command
  15
  16    It is up to you to decide which utilities should be made accessible only
  17 to sysops. It is important that you set the file permissions correctly. All
  18 utilities should have access to the BBS data files.  We will attempt to
  19 address each program individually.
  20
  21
  22   AIDEPOST
  23
  24    The nature of this program is rather simple. Standard input (stdin) is
  25 converted into a message, filed in the main message file (msgmain), and posted
  26 in the Aide> room. This is useful for keeping transcripts of system activity
  27 that has to do with the BBS. You might even elect to send all of your system
  28 logs there, too.
  29
  30    aidepost also accepts the usage "aidepost -rTargetRoom", where TargetRoom
  31 is the name of a room to which you'd like the message to be sent.
  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    The "whobbs" utility is smart enough to know when it is being invoked by a
  48 web server as a CGI program.  In this situation, it will output its listing as
  49 a nicely formatted web page instead of plain text.  This makes it easy to just
  50 put a link to the whobbs binary in your cgi-bin directory, allowing a quick and
  51 easy way for web surfers to see who is online.
  52
  53    Running the <W>ho is online command from the client does *not* call this
  54 utility.  It has this functionality built in.
  55
  56
  57   STATS
  58
  59    (NOTE: this program no longer uses the "curses" library.)   It prints
  60 various statistics on the screen based on the calllog file, such as number
  61 of connects, number of logins, number of logouts, number of disconnects,
  62 bad password attempts, etc. All statistics are provided in three figures:
  63 times per call, times per day, and total times.
  64    After this screen appears, you may press return for the next screen. This
  65 is a graphic representation of system usage, broken down into 20 minute
  66 segments of the day.  This will show you when your peak usage is.
  67    Press return again and the stats program will list your system's top
  68 20 callers.
  69    The final screen lists the twenty users with the highest post per call
  70 ratios.  Unline the other screens, this statistic is extracted from the user
  71 file itself rather than the call log.
  72
  73  stats may be called with the "-b" option to run in batch mode.  In this case,
  74 it skips all the prompts and just prints everything out in one bulk output.
  75 Or it may be called with the "-p" option to only print the Post-to-Call
  76 ratios and nothing else.
  77
  78
  79   MSGFORM
  80
  81    On occasion, I have had messages in Citadel/UX binary format that I have
  82 wanted to view. Or needed a way to view a network spool file. Or wanted to
  83 directly examine parts of msgmain. This program is a simple message formatter.
  84    msgform reads standard input, scanning for binary messages, starting
  85 with an <FF> byte and ending after the final NULL, and print as many as it
  86 finds until it encounters EOF.
  87    You could use this utility along with netproc to provide printouts or
  88 archives of certain rooms.
  89
  90
  91   USERLIST
  92
  93    This is a program to print the userlist. There are two flags that may be
  94 set when running this program. When called without any arguments, userlist
  95 will display all users (except those who have chosen to be unlisted), their
  96 user numbers, times called, messages posted, screen width, and date of their
  97 most recent call.
  98
  99    userlist is simply the same user listing code that is in the client, made
 100 into a standalone utility for convenience.
 101
 102
 103   READLOG
 104
 105    Called without any arguments, readlog dumps the contents of the calllog
 106 file. This file records all times the Citadel/UX program has been started, and
 107 at what baud rate, as well as logins, proper logouts, loss of carrier (SIGHUP),
 108 bad password attempts, and new user logins.
 109
 110
 111   SENDCOMMAND
 112
 113    sendcommand will interpret its arguments (except for "-hDIRNAME") as a
 114 server command, which is sent to the server.  Commands which require textual
 115 input will read it from stdin.  Commands which generate textual output will
 116 be sent to stdout.
 117
 118    This utility is intended to be used to enable Citadel server commands to be
 119 executed from shell scripts.  Review the script called "weekly" which ships
 120 with the Citadel distribution for an example of how this can be used.
 121
 122    NOTE: be sure that this utility is not world-executable.  It connects to the
 123 server in privileged mode, and therefore could present a security hole if not
 124 properly restricted.
 125
 126
 127   --------------------------------------------------------------------------
 128
 129    That should cover all of the included utilities.
 130  For more information, visit the Citadel/UX web site at UNCENSORED! BBS
 131  http://uncnsrd.mt-kisco.ny.us
 132