Chapter 2: Sysop Theory 14 2 Sysop Theory Before getting into the nitty-gritty details of what buttons to push to get which results, let us first force down your throat some theory about what you're going to be dealing with. You can forget about it after the final exam, if you wish. 2.1 Your Callers You are presumably going through all of this because you wish to have people of some type call your system and do something with it. These callers are your reason for running a BBS. While other systems offer a vast array of access and status levels, the general Citadel philosophy of simplicity holds here, meaning that there are no real preferential user access levels. Despite that fact, there do need to be some ways to handle special cases. See Section 5.2 [User Status Commands], page 80, for the commands to assign the various user attributes. As of this writing, the attributes are: o __The Sysop__. That's you, the System Operator, and there's only one of you unless you share the duties with other people, or somebody else has access to your computer while it's running Fnordadel. You can do anything within reason, and a few things beyond reason. Fnordadel allows you to define the name used by the Sysop in `ctdlcnfg.sys', using the parameter #sysop. You should set this up correctly. (If your system really has more than one Sysop, set the #sysop parameter to whichever one has direct access to the system or uses the system most, or just pick a name from a hat. Alternatively, leave #sysop undefined. See Chapter 5 [The Sysop Command Reference], page 75, for more discussion on Sysop matters.) o __Co-Sysops__. You may additionally designate any number of other users on your system as ``Co-Sysops'', by assigning them Sysop privileges. This means that they have virtually unlimited ability to use any command, *except* those in the Sysop menu (accessed by `^L' at the main room prompt). To let such people have access to the Sysop menu as well, you need to give them the system password. Note that anyone who has been given Sysop privs is also automatically given Aide privs. o __Aides__. These are people that you wish to have help you operate, maintain and control your system. They can do things like delete, copy or move messages, and they may do a certain amount of room editing, floor maintenance and other things. In general, however, they can't do much to change the basic nature of things (e.g. alter networking parameters, do things involving access to your storage devices, etc.). o __Twits__. These are users that you have decided are too detrimental to have continued access to your system, but whose user accounts you don't simply wish to kill, lest they immediately sign back on again and continue where they left off. Twits have most commands disabled; this includes the ability to post messages! Chapter 2: Sysop Theory 15 o Everybody else. This is the group of people who are not the Sysop, Co-Sysops, Aides, or Twits. They comprise the bulk of your user population, most likely. Additionally, the Sysop has control over users' ability to do certain things like send private mail, create new discussion rooms, and post in networked rooms. (Such rooms may well be connected to long-distance systems, and we don't want irresponsible or evil users causing big phone bills!) When you first start your system, it is unlikely that you will wish to grant Aide or Co-Sysop status to many of your users, since you probably won't know many of them at all well. Our advice is to take your time, and pick out some people who will handle the positions responsibly. If chosen wisely, they will be an asset in controlling your system, and in making creative contributions which prevent stagnation. 2.2 Rooms Right from the start, Citadel made use of something called a __room__ to contain messages on a related topic. Fnordadel does the same. A room has a name up to 19 characters in length, which presumably captures the gist of a topic to be discussed by the messages in that room. Some systems you may be familiar with make use of ``message areas'', ``message bases'', ``SIGs'' (Special Interest Groups), etc. They are all basically analogous to rooms, but will typically be few in number and cover broad, static topics. Other systems make use of ``threads'', in which messages are related to each other by a common subject field (for example) rather than physical location. Callers travel up and down the threads one message at a time, and now and then jump to a new thread. Still other systems have no way to organise messages; they are all stored in one giant mass that is hard to wade through as a user, and still preserve one's sanity. We feel that Citadel's room metaphor is much easier to use than a threading scheme, offers better organization than one massive message area, and permits better dynamic flow of discussion than bulky SIGs or message bases. As callers use your system, they will move from room to room reading new messages, and posting replies as they see fit. If the topic of a room drifts off on a tangent (as is common), you as Sysop may exercise control to bring it back on track, change its name to suit the new trend of discussion, move the off-topic messages into a newly-created room, or kill the room entirely if none of the above options are worth the effort. The basic room can be specialised in a number of ways to meet various needs. Some of the attributes are: o __Permanent__. Normally, empty rooms will be purged by the system from time to time. There is also a command for doing this explicitly (see .A(ide) D(elete-empty-rooms) in Section 4.1.2 [The .A(ide) command], page 63). You may not always wish rooms to disappear if they go empty, so you may designate them permanent, and they will stick around. Chapter 2: Sysop Theory 16 o __Anonymous__. Rooms of this type are used for discussions where callers may wish to remain totally unidentified. None of the usual message header information is stored or shown by the system, just a message number. o __Private__. These rooms are for carrying out activities that are not to be viewed by all callers to the system. Only users who are told of the complete room name are able to get into it. And once a user knows the room's name, he can't be barred from it short of altering the name and reinviting all the other users. o __Invitation-only__. These rooms are just like the above type, with one difference. Users must be invited into them with a system command; knowing the full name is not sufficient to gain access. If a caller's presence is no longer desired, eviction from the room is also easily possible, without choosing a new room name. o __Read-only__. Rooms of this type can only have messages entered in them by the Sysop, Co-Sysops or Aides. A typical use for such a room is for announcements that you wish people to have access to, uncluttered by comments from other callers. o __Directory__. Rooms of this type are used to give callers access to your storage device(s) (RAM, disk or hard drives), for the purposes of file uploading and/or downloading. Each directory room is tied to a specific disk directory somewhere, so you can give different people access to different collections of files. Normal discussion activities are permissable in directory rooms. o __Network__ or __Shared__. Rooms of this type are linked via the Citadel network (or any other supported) to other systems that also carry the same rooms. Messages entered in these rooms will be transferred among all the systems sharing the room, thus permitting a much larger cross-section of callers to participate in the discussion, no matter their geographical locations. Note that these attributes can be mixed, so it is possible to have, say, a shared, directory, read-only, private, anonymous, permanent room. In order to distinguish between the different types of room that can be found, Fnordadel adds a special character following the room name in many places where room names are shown. They are as follows: `]' designates a directory room `)' designates a shared (network) room `:' designates a shared directory room `>' designates all other types of room From time to time in the following chapters, you will see references to the term __room prompt__. The room prompt is where users are sitting on the system when nothing is going on, and Fnordadel is waiting for a command to be entered. It's called the *room* prompt because the system displays the name of the room in which the user is sitting. Chapter 2: Sysop Theory 17 2.3 Floors Some years after the development of Citadel, numerous systems were getting to be quite large. Rooms permit the organization of messages, but when there are 50 and more rooms, they need to be organized themselves. Thus __floors__ were developed, and are to rooms as rooms are to messages: rooms group related messages, while floors group related rooms. If callers choose not to operate in floor mode, they will see your system as it would have been before floors came about. If they choose floor mode, however, they will see collections of rooms through which they can navigate, in addition to normal room-to-room movement. This permits efficient activites with groups of rooms. Usually all rooms on a floor are somehow related, just as all messages in a room are related. The advantage of this is extra organization that doesn't get in anybody's way. Even if floor mode is chosen by a user, it does not add any inconvenience to his/her use of the system. 2.4 Scrolling __Scrolling__ is a term commonly used to describe the way many aspects of a Citadel work. A good mental image of scrolling is simply to picture any circular, oval, or otherwise closed, race-track. Racers on the track start at the beginning, and loop around it forever after, unless somebody or something stops them. A number of things in Fnordadel also scroll. The largest is probably going to be the message file, which is where all the messages entered in all the rooms are kept. Messages get placed into it at the beginning, and continue being added until the physical end of the file is reached. At this time Fnordadel (and all Citadels) loops back to the start and overwrites old messages there with continued new entries. In this fashion, your system efficiently organizes all messages on your storage device for you, and also automatically deletes old messages. If you find that the message file scrolls faster than you would like, increase its size with the mexpand utility (see `mexpand.man'). Conversely, if the file is not scrolling fast enough, decrease its size with the mshrink utility (see `mshrink.man'). Another thing that scrolls is your user file. This file contains all information known about your users, and has space for a fixed number of users, which you specify. When that space is used up, the next new user to sign onto your system will cause the user file to scroll. The system picks the user who has not signed on for the longest period of time, and tosses the account to make room for the new arrival. Again, efficient use of storage, and no maintenance for the Sysop. (Note that the system will scroll you and your Aides and Co-Sysops with equal efficiency, so be sure you all sign on regularly!) Room contents are yet another thing that --- you guessed it --- scroll. This is because the messages in rooms get overwritten by the scrolling action of the main message file. Thus room content is always current to Chapter 2: Sysop Theory 18 one degree or another (it depends how large the message file is), and the Sysop doesn't have to lift a finger to keep things that way. 2.5 Modes of Operation Fnordadel has four distinct modes of operation, and it's a good idea to understand what the differences are, since they determine who can do what when. 2.5.1 Modem mode When you are not using the system, which is hopefully most of the time (unless you really like reading your own commentary), Fnordadel is in __modem mode__. All this means is that it is ignoring almost everything typed at the console, and is either handling commands entered by a user who called, or else waiting for a call to come in. There are only two ways out of modem mode. The most common is for you, the Sysop, to hit the `' key at the console, and enter console mode (see below). The other is for the software to crash in flames. Fortunately, the latter never happens. 2.5.2 Console mode When you are using the system, Fnordadel is in __console mode__ (unless you dialed in from elsewhere, but that's cheating). It is possible for the system to be in console mode while a user is connected from remote. It is advised that you not enter console mode, however, except when the user is at a room prompt. Otherwise, strange things may happen when you hit `' to take over. When the system is in console mode, you can carry out normal BBS activites such as reading and entering messages. If nobody is logged in, Fnordadel may restrict what you can do based on some of the settings in `ctdlcnfg.sys'. See `ctdlcnfg.doc' for details. In any case, being in console mode will let you do most things, logged in or not, plus it also gets you access to the Sysop special functions menu without having to enter the system password. See Chapter 5 [The Sysop Command Reference], page 75, for more details. To return the system to modem mode --- which you must do in order for it to receive calls again, or for an online user to finish what he or she was up to --- use the [M]odem mode command in the Sysop menu. Again, see Chapter 5 [The Sysop Command Reference], page 75. Chapter 2: Sysop Theory 19 2.5.3 Chat mode __Chat mode__ is unlike the two previous modes in two ways. First, Fnordadel pays attention to characters coming in from both the console and the modem, and echoes all of them to the screen. This is how you talk to your users when they're on the system. Try it, you might like it! Second, virtually no commands are available in chat mode. It is intended for purely discussion purposes. To exit chat mode, hit `'. Fnordadel will return to either modem or console mode according to what mode was in effect when chat mode was started. If the mode is console, don't forget to return Fnordadel to modem mode so the user can finish his or her activities. Chat mode is also used when you dial out from your system and connect with other systems as a user, yourself. In these cases you're chatting with another BBS instead of a user. If you press `' while still online with a remote system, you'll probably want to reconnect with it once you've finished whatever caused you to hit `'. To do this, just execute the [C]hat command yourself, or use the [G]otomodem... command from the Sysop menu. See Section 3.1.1.3 [Other room prompt commands], page 29, and Section 5.1 [Sysop Special Functions], page 75, for details. 2.5.4 Network mode __Network mode__ is unlike the previous three modes, in that nobody is logged in to the system. Instead, it is communicating with other Citadel(s) of some kind, somewhere, for the purpose of transferring private mail, shared rooms, files, and so on. When the system is in networking mode, nobody else can use it until it finishes what needs doing. Clearly, the more time your system spends networking, the less time your users and yourself can be online. So configure your network controls to give a good balance between system availability and timely communication with your networking partners. 2.6 Configuring If you read Chapter 1 [Fifteen Minute Guide], page 5, on how to start your system as quickly as possible, you will have encountered the instructions to modify a file called `ctdlcnfg.sys' and run a program called configur. Here is more treatment of that information, or a first look if you skipped that chapter like someone who wants to get all the facts before mucking with things. Chapter 2: Sysop Theory 20 2.6.1 The ctdlcnfg.sys file This is the Fnordadel configuration file, an ASCII text file that can be edited with any text editor or word processor which can output ASCII files. It contains a truck-load of system parameters and options that let you tell Fnordadel things it needs to know, and let you set up some non-essentials to give your system a unique flavour. For details on the contents of this file, see `ctdlcnfg.doc'. Please be sure that the contents of this file always accurately describe your system! There are utility programs that will modify various parameters of your system, but they *do not* alter the contents of `ctdlcnfg.sys'. It is up to you to edit the file and change the appropriate values. If you don't, *pure evil* will result. In order for the information in this file to actually get communicated to Fnordadel, it must be run through the configuration program, configur. Speaking of which ... 2.6.2 The configur program configur is the Fnordadel configuration program. It processes everything you've entered in `ctdlcnfg.sys' and checks for errors of omission or commission, displaying error messages as necessary. The error messages will hopefully pin-point the problem for you. You can always look at `ctdlcnfg.doc' for a (bloated) example of a correct file. If everything goes well, the result of running this program will be yet another file called `ctdltabl.sys'. 2.6.3 The ctdltabl.sys file This is the file which contains the distilled essence of `ctdlcnfg.sys', in a binary form that Fnordadel can accept; it also contains various system tables (like indices into the message file, log file and so on) which change with time. Fnordadel will not run if this file is not present, and it will die horribly or act terribly if the file is incomplete, corrupted, or otherwise screwed up. Likewise with many of the Fnordadel utility programs. For this reason, Fnordadel and some of the more complex utility programs will actually delete `ctdltabl.sys' when you run them, and then write it back out again when they exit properly. This prevents the ugly situation, for example, of running your Fnordadel for a few days, and having it crash messily, leaving around a `ctdltabl.sys' that no longer reflects the current status of your system. If you tried to rerun your system without reconfiguring, it would be a Very Bad Thing. As things stand, a bad crash by Fnordadel or a utility will leave you without `ctdltabl.sys', forcing you to rerun configur before doing anything else. Chapter 2: Sysop Theory 21 This point bears emphasis: *losing your `ctdltabl.sys' file means almost nothing*. You can always regenerate it by running configur, as long as no other system files have been damaged or deleted. If you suspect anything weird is going on with your system, the first thing you should do is *back everything up*, and *not* over top of an existing backup. The second thing to do is delete `ctdltabl.sys' and run configur. Hopefully this will fix things up. 2.7 Command Structure Before we start with particular groups of commands, let's look at the structure of Citadel commands. One design feature of the command system is ``orthogonality'', which is a nice big word that roughly means ``consistency''. Or, things look the same one place as in another. Keep this in mind and it will speed you on your way to mastering the system's complexity. Keep one other thing in mind: At almost every conceivable point in the system where it is waiting for you to enter a command, you can press the `?' key to see a list of the currently available commands. ``This system of menus isn't quite as convenient as ones that pop up automatically as with other BBSes'', argue some people, but it is another facet of Citadel's philosophy --- stay out of the way unless called for. And now, the two basic types of commands. 2.7.1 Single-key commands The so-called __single-key__ commands are the basic bread and butter for you and your users. They are the common functions that everybody wants to use all of the time, and they have been streamlined as much as possible to permit people to do what they want without wading though layers of barriers (what other systems call ``menus''). These commands are all invoked by pressing a single key, and do not need to be followed by a carriage-return. To be a successful Fnordadel user, you only have to know five of the single-key commands: o [G]oto the next room o read [N]ew messages o [E]nter a message o [P]ause reading o [S]top reading These five commands, along with the obvious need to know [L]ogin, [?] and [T]erminate, will satisfy most people who call. Chapter 2: Sysop Theory 22 2.7.2 Multi-key/extended commands It would be nice if all functions of the software could be called up using single key-strokes. Fortunately---yes, that's ``fortunately''- --there are too many of them to permit this. For example, there are those individuals who will want to be able to do things like compose messages (probably long ones) off-line and then upload them in one shot to your board. There will be those people who will want to grab whatever downloadable files you've got on your board. There will be those who want to upload stuff to your board. (I know, it's hard to believe, but there is the occasional altruistic soul around.) And, naturally, there will be those individuals who will want to do some odd variant of any of those things, or a host of others. Yourself, Co-Sysops, and Aides are probably good examples of such people. To accommodate this need, Fnordadel uses __multi-key__ or __extended__, commands. In contrast to the single-key commands, multi-key commands start with a mode character and are followed by a number of other command characters. Some extended commands also take a user name, file name or date; these must be terminated by a carriage return. The mode character tells Fnordadel that you're using an extended command instead of a single-key command, and what type of extended command it will be. Normal extended commands that deal with rooms, messages and files start with a period, `.'. Floor extended commands, which deal with entire floors, start with a semi-colon, `;'. Door extended commands, which permit the running of other programs from within Fnordadel, start with an exclamation mark, `!'. Most extended commands will either be ``enter'' or ``read'' operations. Citadel defines any command you use that results in data being sent to the system as an ``enter'' command. Any command that results in data being sent from the system to you is a ``read'' command. Thus, to read new messages in the current room, you could use the extended command .rn which the system will display as: .read new To download a file `blort.txt' using the Xmodem file transfer protocol, you would also do a read operation: .rxfblort.txt which is displayed like: .read xmodem file blort.txt followed by an ``are you ready'' sort of prompt. Chapter 2: Sysop Theory 23 To get even trickier, you could download all new messages in the current room from the user ``Foobar'' since 90Jul01, to your own system, using the Ymodem file transfer protocol, for leisurely perusal: .ryu+nFoobar89Jul01 which looks like: .read ymodem user after new - which user: Foobar After what date: 89Jul01 You may not notice, but in all these cases, there is a pattern to the command. It always starts with a `.', then specifies the main command followed by some options, and finishes with what the command is supposed to deal with (``new'' implies ``new messages'', while ``file'' explicitly means ``files''). The system will then prompt for further data as needed by some of the options. To summarize the structure:
In the final example above, `.ryu+n', we have: `.' for ``extended command''
`r' for ``read'' `yu+' for ``ymodem user after'' `n' for ``new messages'' ``which user'' and ``After what date'' This patterning, which aids a user in knowing what to expect and even helps him/her to anticipate how commands should be strung together, is the ``orthogonality'' mentioned before. Orthogonal command structures always do the same or similar things in the same way, or by using the same structure. It is one of the strengths of Citadel, and one of the glaring weaknesses of many other systems. It makes your system look unlike anything you or your users may have encountered before, but we think it's worth it.