From owner-freebsd-doc Thu Nov 30 10:17:49 2000 Delivered-To: freebsd-doc@freebsd.org Received: from cfcl.com (cpe-024-221-169-054.ca.sprintbbd.net [24.221.169.54]) by hub.freebsd.org (Postfix) with ESMTP id 3024C37B400 for ; Thu, 30 Nov 2000 10:17:43 -0800 (PST) Received: from [192.168.168.205] (cerberus [192.168.168.205]) by cfcl.com (8.9.3/8.9.3) with ESMTP id KAA30072 for ; Thu, 30 Nov 2000 10:17:26 -0800 (PST) (envelope-from rdm@cfcl.com) Mime-Version: 1.0 Message-Id: In-Reply-To: <00113006572909.11309@mukappa.home.com> References: <4910.975533445@axl.fw.uunet.co.za> <3A262AF9.5020108@i-clue.de> <00113006572909.11309@mukappa.home.com> Date: Thu, 30 Nov 2000 10:17:40 -0800 To: freebsd-doc@freebsd.org From: Rich Morin Subject: Re: documenting nonexistent files Content-Type: text/plain; charset="us-ascii" ; format="flowed" Sender: owner-freebsd-doc@FreeBSD.ORG Precedence: bulk X-Loop: FreeBSD.org At 6:57 AM -0700 11/30/00, Mike Porter wrote: >On Thu, 30 Nov 2000, Christoph Sold wrote: >> Great work. I like it. Wish I had such a thing >> when I started to stumble around FreeBSD... > >Me Too! > Thanks. FWIW, what I did was to take some of the info that I'm collecting for Meta and mash it into (something like) the format that was being used for the README.examples file. In Apple's A/UX operating system, BTW, there was a file called /FILES, which gave a short description of every file on the distributed system (including some "nonexistent" files). I have refrained from including any descriptive information that would cause the format to expand past one line per item. My feeling is that the README2.examples file (when created) and the comments in the example files themselves are better suited to deal with detailed (read, long-winded) explanations. I liked the idea of using "O" for obsolete, but that would have gotten in the way of the +/- distinction, so it lost out. >> * Is my characterization of /etc/make.conf.local correct? > >No. If that's still a valid file, it's like rc.conf.local ... Hmmm; I got my interpretation from /usr/share/mk/sys.mk: .if exists(/etc/make.conf.local) .error Error, original /etc/make.conf should be moved to the /etc/defaults/ directory and /etc/make.conf.local should be renamed to /etc/make.conf. .include .endif >> * Is the saving of these files automated? If so, why aren't >> /etc/passwd and other files being saved? > >No automated saving of files is done at upgrade to my knowledge. Sorry; I wasn't clear. There should be an "example-saving" script that runs when the FreeBSD distribution is being build. Otherwise, the files in /usr/share/examples/etc won't be reliably present, let alone current copies of the originals. Anyway, buoyed by the nice comments and suggestions, I have spent a bit more time on README.examples; here is my current snapshot. -r ===== $FreeBSD: usr/share/examples/etc/README.examples,v ... The /usr/share/examples/etc directory contains both the original distribution versions of the files which are shipped in /etc and "starter" versions of files which are NOT present by default, but which can (and occasionally should) be created for some purpose. This is intended to make it easier to recover when the /etc versions are accidentally deleted or broken beyond repair. A proper backup system and regular snapshots (e.g., via RCS or CVS) is recommended, however, for more safety. The /etc subtree contains (and can contain) a number of files. For more detailed information on these files, see the referenced man pages, README2.examples, and the example files (if present). Legend: + generally present by default (e.g., at installation) - generally absent by default (e.g., at installation) / directory @ symbolic link 1 may be present, depending on hardware architecture. 2 file extension depends on network interface hardware (obs.) obsolete, but retained for backwards compatibility adduser.conf + configuration file for adduser(8) aliases + sendmail(8) aliases(5) file amd.conf - configuration file for amd(8) amd.map + filesystem automounter (see amd(8)) lookup resolution map apmd.conf + configuration file for apmd(8) auth.conf + authentication capability database (see auth.conf(5)) ccd.conf - startup script for ccd (4), run by /etc/rc crontab + system scheduled command table (see crontab(5)) csh.cshrc + sample .cshrc (see csh(1)) csh.login + sample .login (see csh(1)) csh.logout + sample .logout (see csh(1)) daily.local - script, run by /etc/periodic/daily/999.local (obs.) defaults / default configuration files (do NOT modify) make.conf + configuration variables for system builds (see make(1)) pccard.conf + configuration file for pccardd(8) rc.conf + system configuration info (see rc.conf(5)) disktab + disk description file (see disktab(5)) dm.conf + configuration file for games (see dm(6)) dumpdates + log file for dump(8) fbtab + configuration file for login(1) (see fbtab(5) fstab + static information about the filesystems (see fstab(5)) ftpusers + user restriction file for ftpd(8) (see ftp(1)) gettytab + defines port configuration for getty(8) (see gettytab(5)) gnats / gnats control files group + group permissions file (see group(5)) host.conf + defines gethostbyname(3)'s name res. order a (see hosts(5)) hosts + predefines names as IP addresses (see hosts(5)) hosts.allow + defines trusted hosts (see hosts_access(5), hosts_access(3)) hosts.deny - defines denied hosts (see hosts_access(5), hosts_access(3)) hosts.equiv + defines system-wide trusted hosts (see hosts.equiv(5)) hosts.lpd + defines trusted hosts for lpd(8) inetd.conf + configuration file for inetd(8) ipsec.local - startup script, run by /etc/rc (see ipsec(4)) isdn / ISDN control files (see isdnd.rc(5), isdnd(8)) kerberosIV / Kerberos control files localtime + binary reference file for localtime(3) locate.rc + configuration file for locate(1) login.access + configuration file for login(8) (see login.access(5)) login.conf + login class capabilities database (see login.conf(5)) mail / sendmail(8) mail transport agent control files sendmail.cf - raw control file; presence tested by /etc/rc * - assorted sendmail(8) control files mail.rc + systemwide initialization files for mail(1) make.conf - override file for defines/make.conf (see make.conf(5)) make.conf.local - make.conf(5) file, saved from before an upgrade manpath.config + configuration file for man(1) master.passwd + "real" user permissions file (see passwd(1), passwd(5)) modems + modem configuration database (see modems(5)) monthly.local - script, run by /etc/periodic/monthly/999.local (obs.) motd + text of the Message of the Day (see motd(5)) mtree / mtree(8) control files namedb / Internet domain server (DNS) control files (see named(8)) localhost.rev + reverse DNS lookup file named.conf + configuration file for named(8) named.root + information on root name servers netstart + network startup script (obs.) networks + see networks(5) newsyslog.conf + configuration file for system log rotator newsyslog(8) objformat + configuration file for objformat(1) opiekeys + opie(4) database of user key information (see opiekeys(5)) pam.conf + configuration file for pam(8) pam.d / directory (if present) of override files for /etc/pam.conf passwd + "public" user permissions file (see passwd(1), passwd(5)) pccard.conf - override configuration file for pccardd(8) pccard.conf.sample - sample configuration file for pccardd(8) (obs.) pccard_ether + configuration script for ethernet pccards (see pccardd(8)) periodic / periodically run scripts (see periodic(8)) daily / scripts that are run daily weekly / scripts that are run monthly monthly / scripts that are run weekly phones + phone number database for tip(1) (see phones(5) pim6dd.conf + configuration file for pim6dd(8) (see pim6dd.conf(5)) pim6sd.conf + configuration file for pim6sd(8) (see pim6sd.conf(5)) printcap + configuration file for lpr(1) (see printcap(5)) profile + system-wide .profile for sh(1) protocols + protocol name data base (see protocols(5)) ptmp - password temporary lock file; presence tested by /etc/rc pwd.db + binary database for pwd(1) rc + system startup script (see init(8), rc(8)) rc.alpha 1 startup script for (Alpha) axp-specific processing rc.atm + networking startup script for atm(8) rc.conf + system configuration information (see rc.conf(5)) rc.conf.local - local configuration override script (see rc.conf(5)) rc.devfs + startup script for devfs(5) rc.diskless1 - general BOOTP startup script, run by /etc/rc. rc.diskless2 - special script; run by /etc/rc per rc.diskless1. rc.firewall + setup system for ipfw(8) rc.i386 1 startup script for (Intel) i386-specific processing rc.isdn + startup script for isdnd(8) rc.local - startup script; run by /etc/rc (obs.) rc.network + network startup script rc.network6 + network startup script for IPV6 (see ip6(4)) rc.pccard + startup script for PC-cards rc.resume + startup script for APM Resume Event rc.serial + sample local startup script fragments rc.shutdown + system shutdown script (see init(8)) rc.suspend + startup script for APM Suspend Event rc.sysctl + startup script for sysctl(8) remote + configuration file for tip(1) resolv.conf + resolver(3) configuration file (see resolv.conf(5)) rmt @ symlink to rmt(8) command rpc + rpc(3) program number data base (see rpc(5)) security + script, run from crontab to do nightly security checks services + service name data base (see services(5)) shells + list of configurable shells (see shells(5)) skel / ??? skey.access + configuration file for skey(1) (see key(1), skey.access(5)) skeykeys + data file for skey(1) (see key(1), skey.access(5)) spwd.db + binary database for pwd(1) ssh / OpenSSH secure shell client control files (see ssh(1)) ssl / OpenSSL control files (see ssl(1)) start_if.* 2 startup script, run by /etc/rc (see ifconfog(8)) sysctl.conf - configuration file for sysctl(8) (see sysctl.conf(5)) syslog.conf + configuration file for syslogd(8) (see syslog.conf(5)) termcap @ symlink to terminal capability data base (see termcap(5)) ttys + defines port configuration for init(8) (see ttys(5)) usbd.conf + configuration file for usb(4) daemon (see usbd.conf(5)) uucp / control files for uucp(1) wall_cmos_clock + ??? weekly.local - script run by /etc/periodic/weekly/999.local (obs.) -- -- Rich Morin: rdm@cfcl.com, +1 650-873-7841, http://www.cfcl.com/rdm Prime Time Freeware: info@ptf.com, +1 408-433-9662, http://www.ptf.com MacPerl: http://www.macperl.com, http://www.ptf.com/ptf/products/MPPE MkLinux: http://www.mklinux.org, http://www.ptf.com/ptf/products/MKLP To Unsubscribe: send mail to majordomo@FreeBSD.org with "unsubscribe freebsd-doc" in the body of the message