Return to README CVS log

Up to [CSRG BSD Unix] / 43BSDTahoe / new / nntp / common

Annotation of 43BSDTahoe/new/nntp/common/README, revision 1.1

1.1     ! root        1:      This directory contains lotsa good stuff common to both
        !             2: the news server, support, and client programs.  The short of it is:
        !             3: 
        !             4: conf.h         Configuration information for NNTP server,
        !             5:                support, and client programs.  Described in detail below.
        !             6: 
        !             7: response_codes.h  These are the #define's of the numeric response
        !             8:                codes in NNTP.  This shouldn't change.
        !             9: 
        !            10: rfc977.h       Things that weren't response codes, but belong somewhere.
        !            11:                These should remain constant.
        !            12: 
        !            13: clientlib.c    This file is a collection of routines which clients
        !            14:                can use to talk to the NNTP server.  The code is
        !            15:                well documented, but briefly, the functions are
        !            16: 
        !            17:                        getserverbyfile Opens a named file and
        !            18:                                        returns the contents,
        !            19:                                        presumed to be a host name
        !            20:                        server_init     Open connection to server
        !            21:                        getsocket       Get a stream socket
        !            22:                        get_server      Get line from server
        !            23:                        put_server      Send line to server
        !            24:                        close_server    Close connection
        !            25: 
        !            26:                It is worth noting that these routines use
        !            27:                buffered I/O, and leave the external variables
        !            28:                "ser_rd_fp" and "ser_wr_fp" (server read/write
        !            29:                file pointers, respectively) floating around
        !            30:                for use by programs which need them.
        !            31: 
        !            32:                In any event, you shouldn't need to screw with
        !            33:                these routines.
        !            34: 
        !            35: conf.h
        !            36: ======
        !            37: 
        !            38:      You will need to screw with this to get the server, support, and
        !            39: client programs running.  Unfortunately, "rrn" has its own ideas of
        !            40: where to look for config information, so there is some duplication of
        !            41: effort here.  With luck, it won't be too great.
        !            42: 
        !            43:      This is sort of a walk through conf.h so you can get some idea of
        !            44: what parameters need to be changed.  The #defines's default value is
        !            45: listed in parenthesis after it's name.  Manual entries mentioned here
        !            46: are in the "doc" directory of the NNTP distribution.
        !            47: 
        !            48:      First are some compile-time type options, for compiling in
        !            49: certain code.  The options should be "#undef"ed if you don't want
        !            50: them, and "#defined" if you do.
        !            51: 
        !            52: ALONE          (undefined)
        !            53: 
        !            54:      Defines whether we're a stand alone version of the server, or
        !            55: whether we're running under inetd.  I suggest you run under inetd.
        !            56: 
        !            57: FASTFORK       (undefined)
        !            58: 
        !            59:      If we're ALONE, then this option tells us not to read the
        !            60: active file when we fork, but rather for the parent daemon to re-read
        !            61: it every READINTVL (below) seconds.  This should make forking off children
        !            62: a little bit faster.
        !            63: 
        !            64: BSD_42         (undefined)
        !            65: 
        !            66:      If you have a 4.2 BSD system (as opposed to a 4.3 BSD system),
        !            67: this needs to be defined.  Really it does only two things: changes
        !            68: the log level to be compatible with 4.2, and automatically defines
        !            69: DBM (below).  If, somehow, you already have ndbm, then you should
        !            70: kill the lines which auto-define it.
        !            71: 
        !            72: DBM            (undefined)
        !            73: 
        !            74:      If you don't have the ndbm routines in your standard library (i.e.,
        !            75: if you're not running 4.3 BSD), you'll have to define this; all it
        !            76: does is replace the ndbm calls with the earlier, unwieldy dbm calls.
        !            77: 
        !            78: vfork          (undefined)
        !            79: 
        !            80:      If you don't have the vfork system call, define vfork to be fork,
        !            81: i.e.,
        !            82: 
        !            83:        #define vfork   fork
        !            84: 
        !            85: If you do have it, use it: it will increase performance on transfer
        !            86: dominated machines by a factor or two or so in nntpd.
        !            87: 
        !            88: SYSLOG         (LOG_NEWS)
        !            89: 
        !            90:      Some systems, such as the Masscomp, do not have a syslog facility.
        !            91: If SYSLOG is undefined, no syslog/openlog calls will be made.
        !            92: Naturally, if SYSLOG isn't defined, LOG (below) cannot be defined.
        !            93: Otherwise, define it to be the name of the facility under which we
        !            94: log stuff.
        !            95: 
        !            96: LOG            (undefined)
        !            97: 
        !            98:      When LOG is defined, we log copious amounts of information via
        !            99: syslog to a special file.  One a busy system like ucbvax, this produces
        !           100: about 100K of log information per day.  Look in ../src/SYSLOG to
        !           101: get an idea of what will be logged.  You can use the scripts
        !           102: provided in ../support to produce statistics on your NNTP server if
        !           103: you run with LOG.
        !           104: 
        !           105: IHAVE_DEBUG    (undefined)
        !           106: 
        !           107:      Enables logging of each message-id as it is offered via the IHAVE
        !           108: command.  This produces huge log files, but is useful if you suspect
        !           109: a site is repeatedly offering the same article to your site after you
        !           110: have rejected it.
        !           111: 
        !           112: XHDR           (defined)
        !           113: 
        !           114:      Enables the XHDR command, which is an extention of the NNTP spec.
        !           115: XHDR allows client programs to see header lines (e.g., subject) from
        !           116: an article or range of articles.  This allows the '=' command in rn
        !           117: to be much faster, IF AND ONLY IF your server machine is fast.  Since
        !           118: this command foists off work on the server, it may be better to leave this
        !           119: undefined if your server machine is heavily loaded.
        !           120: 
        !           121: SUBNET         (undefined)
        !           122: 
        !           123:      If you are running 4.3 BSD or have support for subnets on
        !           124: your local net, this will include subnet support for the access
        !           125: file.  Basically, a routine goes out and looks at all your ethernet
        !           126: interfaces, and figures out subnet masks from them.  It then
        !           127: uses these to resolve subnets from IP addresses.
        !           128: 
        !           129: DAMAGED_NETMASK        (undefined)
        !           130: 
        !           131:      4.3 supports subnet masks of any bit-width, but user programs
        !           132: are *very* hard pressed to deal with masks which are not a multiple
        !           133: of 8 bits wide.  If you have a weird netmask, define DAMAGED_NETMASK.
        !           134: The code which uses it is in server/inet_snetof.c.  This code
        !           135: is a real hack, and you may have to diddle with it to make it work.
        !           136: 
        !           137: GHNAME         (defined)
        !           138: 
        !           139:      Defined if you want to use the 4BSD gethostname() call to
        !           140: determine the name of your system.  This #define is only used
        !           141: by the mini-inews when posting news.  Some reasons you might not
        !           142: want to use this are: if your UUCP/news name is different than
        !           143: your internet name; if your gethostname() currently doesn't
        !           144: return fully-qualified names (e.g., 4.2) but you may "upgrade"
        !           145: to 4.3 (and return fq'd names) shortly, and you'd rather not
        !           146: have to recompile news...  See UUNAME below.
        !           147: 
        !           148: UUNAME         (undefined)
        !           149: 
        !           150:      If this is defined, mini-inews will get the hostname out
        !           151: of /etc/uucpname or /local/uucpname.
        !           152: 
        !           153: >>>    If GHNAME and UUNAME are undefined, mini-inews will     <<<
        !           154: >>>    get the host name from /usr/include/whoami.h            <<<
        !           155: 
        !           156: TIMEOUT                (2 hours)
        !           157: 
        !           158:      If a server is idle in command mode for TIMEOUT amount of time,
        !           159: it will close the connection with an error message.  This prevents
        !           160: old servers from clogging the system.  Timeout should be at least two
        !           161: hours so people can go eat lunch and leave an rn on their terminal.
        !           162: 
        !           163: XFER_TIMEOUT   (30 minutes)
        !           164: 
        !           165:      This is like TIMEOUT, above, but takes effect when the server is
        !           166: receiving news via IHAVE or POST.  If at least one line is not received
        !           167: in XFER_TIMEOUT amount of time, the server aborts with an error.
        !           168: 
        !           169: DOMAIN         ("uucp")
        !           170: 
        !           171:      If domain is defined, it specifies that whatever it is defined
        !           172: as will be appended to host names; this is for posting news when
        !           173: your hostname() doesn't return your fully-qualified domain name.
        !           174: If your hostname system call does return a fully-qualified name,
        !           175: simply undef DOMAIN.
        !           176: 
        !           177: 
        !           178: SERVER_FILE    ("/usr/local/lib/rn/server")
        !           179: 
        !           180:      This file contains the name of the machine which runs the
        !           181: news server.  Mini-inews, rrn, and getactive all use the contents
        !           182: of this file.  The idea behind this is that you don't have to have the server
        !           183: compiled into anything, and can have the same binaries across
        !           184: machines which have different news servers.
        !           185: 
        !           186:      You must edit this file, and add a single line which contains
        !           187: the name of the news server for each machine which runs rrn.
        !           188: 
        !           189:      If you have multiple news servers on your network, users can
        !           190: select which one they want to use via the NNTPSERVER environment
        !           191: variable, which will override the contents of SERVER_FILE.  Simply
        !           192: set NNTPSERVER to be the name of the machine whose news server you
        !           193: want to use.
        !           194: 
        !           195:      If you are afraid of people abusing a particular news server
        !           196: via NNTPSERVER, you should edit the access file for that news server
        !           197: accordingly.  Security begins at home.
        !           198: 
        !           199: >>> rrn, mini-inews, and getactive NO LONGER have compiled in server names <<<
        !           200: >>> Be sure to create the SERVER_FILE as mentioned above, or you'll lose!  <<<
        !           201: 
        !           202: POSTER         ("news")
        !           203: 
        !           204:      If your nntpd is run as root, nntpd will attempt to setuid()
        !           205: and setgid() to the uid and gid of whoever POSTER is defined as.
        !           206: If your nntpd isn't running as root (i.e., it might run as "usenet"),
        !           207: either undefine this, or define it to be a user which exists but
        !           208: is not used -- the setuid will fail in any event.
        !           209: 
        !           210: Next, we have some common files:
        !           211: 
        !           212: ACTIVE_FILE    ("/usr/lib/news/active")
        !           213: 
        !           214:      Specifies the location of the "active" file.
        !           215: 
        !           216: ACCESS_FILE    ("/usr/lib/news/nntp_access")
        !           217: 
        !           218:      Specifies the location of the remote access file.
        !           219:      See the manual entry, nntpd.8c, for a better explanation.
        !           220:      A sample access file is in ../support/access_file.
        !           221: 
        !           222: HISTORY_FILE   ("/usr/lib/news/history")
        !           223: 
        !           224:      Specifies the location of the "history" file.
        !           225:      This is used with NEWNEWS and ARTICLE/HEAD/BODY/STAT when
        !           226:      given an message-id argument.
        !           227: 
        !           228: INEWS          ("/usr/lib/news/inews")
        !           229: 
        !           230:      Specifies the location of inews, for posting.  Note that this
        !           231:      is NOT the same as the mini-inews in the inews directory
        !           232:      supplied with the NNTP distribution, which should only
        !           233:      be installed on client machines.  INEWS should be the pathname
        !           234:      of real, live, honest-to-God inews.  Your inews may be
        !           235:      in a different place, such as /usr/bin/inews.
        !           236: 
        !           237: SPOOLDIR       ("/usr/spool/news/")
        !           238: 
        !           239:      This is the directory where news is stored.  Note that
        !           240:      the trailing / is important.
        !           241: 
        !           242: RNEWS          ("/usr/bin/rnews")
        !           243: 
        !           244:      Specifies the location of the rnews program which is used
        !           245:      for dealing with news received from other systems via the
        !           246:      IHAVE command; it is often a link to inews.
        !           247: 
        !           248: STAT_FILE      ("/usr/lib/news/mgdstats")
        !           249: 
        !           250:      When the support program "mkgrdates" is run, it keep stats
        !           251:      in a file to tell whether or not to rebuild its database
        !           252:      the next time it is run; this is the file the stats are kept
        !           253:      in.  Needless to say, it must be writable by whatever user-id
        !           254:      runs "mkgrdates".  See the manual entry "mkgrdates.8c" for
        !           255:      more info.
        !           256: 
        !           257: NGDATE_FILE    ("/usr/lib/news/groupdates")
        !           258: 
        !           259:      Specifies the location of the newsgroup creation date file.
        !           260:      See the manual entry for both nntpd.8c and mkgrdates.8c for
        !           261:      more info.
        !           262: 
        !           263: READINTVL      (600 seconds)
        !           264: 
        !           265:      If the server is compiled with FASTFORK and ALONE, then this number
        !           266:      tells how often to check if the active file has changed (and to
        !           267:      read it in if it has changed since the last time).  See README
        !           268:      in the "server" directory of the NNTP distribution.  If you are
        !           269:      not compiled with FASTFORK and ALONE (hint: you're not going to),
        !           270:      don't worry about this.
        !           271: 

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.