diff --git a/en_US.ISO8859-1/articles/cvs-freebsd/article.sgml b/en_US.ISO8859-1/articles/cvs-freebsd/article.sgml index abc02890fc..2f0ad424fc 100644 --- a/en_US.ISO8859-1/articles/cvs-freebsd/article.sgml +++ b/en_US.ISO8859-1/articles/cvs-freebsd/article.sgml @@ -1,690 +1,690 @@ %man; %authors; %trademarks; ]>
Setting up a CVS repository - the FreeBSD way Stijn Hoop
stijn@win.tue.nl
 2001 2002 2003 Stijn Hoop $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.general; - This article describes the steps I took to setup a CVS repository + This article describes the steps I took to set up a CVS repository that uses the same scripts the FreeBSD project uses in their setup. This has several advantages over a stock CVS setup, including more granular access control to the source tree and generation of readable email of every commit. Introduction Most of the open source software projects use CVS as their source code control system. While CVS is pretty good at this, it has its share of flaws and weaknesses. One of these is that sharing a source tree with other developers can quickly lead to a system administration nightmare, especially if one wishes to protect parts of the tree from general access. FreeBSD is one of the projects using CVS. It also has a large base of developers located around the world. They developed some scripts to make management of the repository easier. Recently, these scripts were revisited and normalized by &a.joe; to make it easier to reuse them in other projects. This article describes one method of using the new scripts. To make the most use of the information in this article, you need to be familiar with the basic method of operation of CVS. First setup It might be best to first perform this procedure with an empty test repository, to make sure you understand all consequences. As always, make sure you have recent, readable backups! Initializing the repository The first thing to do when setting up a new repository is to tell CVS to initialize it: &prompt.user; cvs -d path-to-repository init This tells CVS to create the CVSROOT administrative directory, where all the customization takes place. The repository group Now we will create the group which will own the repository. All committers need to be in this group, so that they can write to the repository. We will assume the FreeBSD default of ncvs for this group. &prompt.root; pw groupadd ncvs Next, you should &man.chown.8; the directory to the group you just added: &prompt.root; chown -R :ncvs path-to-your-repository This ensures that no one can write to the repository without proper group permissions. Getting the sources Now you need to obtain the CVSROOT directory from the FreeBSD repository. This is most easily done by checking it out from a FreeBSD anonymous CVS mirror. See the relevant chapter in the handbook for more information. Let us assume that the sources are stored in CVSROOT-freebsd in the current directory. Copying the FreeBSD scripts Next, we will copy the FreeBSD CVSROOT sources into your own repository. If you are accustomed to CVS, you might be thinking that you can just import the scripts, in an attempt to make synchronizing with later versions easier. However, it turns out that CVS has a deficiency in this area: when importing sources into the CVSROOT directory, it will not update the needed administrative files. In order to make it recognize those, you will need to checkin each file after importing them, losing the value of cvs import. Therefore, the recommended method is to simply copy over the scripts. It does not matter if the above paragraph did not make sense to you—the end result is the same. Simply check out your CVSROOT and copy the FreeBSD files over your local (untouched) copies: &prompt.user; cvs -d path-to-your-repository checkout CVSROOT &prompt.user; cd CVSROOT &prompt.user; cp ../CVSROOT-freebsd/* . &prompt.user; cvs add * Note that you will probably get a few warnings about some directories not being copied; this is normal, you do not need those. The scripts Now you have in your working directory an exact copy of the scripts that the FreeBSD project itself uses for their repository. A summary of what each file is used for is included below. access - this file is not used in the default setup. It is used in the FreeBSD project specific setup, where it controls access to the repository. You can remove this file if you do not wish to use this setup. avail - this file controls access to the repository. In this, you can specify groups of people that are allowed access to the repository, as well as disallow commits on a per-directory basis. You should tailor it to contain the groups and directories that will be in your repository. cfg.pm - this file parses your configuration, and provides the default configuration. You should not make changes to this file. Instead, put your configuration changes in cfg_local.pm. cfg_local.pm - this file contains all configurable parameters of the system. You should configure all sorts of settings here, such as where commit mail is send, on what hosts people can commit, and others. More information on this below. checkoutlist - this files lists all files under control of CVS in this directory, apart from the standard ones created by cvs init. You should edit this to remove some FreeBSD-specific files. commit_prep.pl - this script performs various pre-commit checks, based on whether you enabled them in your cfg_local.pm. You should not have to touch this. commitcheck - this script is invoked directly from CVS. It first checks if the committer has access to the specified part of the tree using cvs_acls.pl, and then runs commit_prep.pl for the various pre-commit checks. If those are OK, CVS will allow the commit to proceed. You should not have to touch this file. commitinfo - this file is used by CVS to determine which script to run before a commit—in this case commitcheck. You should not have to touch this file. config - the configuration file for this repository. You should change this as needed, but most administrators can probably leave the defaults. More information on the options that can be set here can be found in the CVS manual. cvs_acls.pl - this script determines the committers identity, and whether he/she is allowed access to the tree. It does this based on the avail file. You should not have to touch this file. cvsignore - this file specifies files that CVS should not checkin in the repository. You can edit this as you wish. More information about this file is available in the CVS manual. cvswrappers - this file is used by CVS to enable or disable keyword expansion, or whether a file should be considered binary. You can edit this as you wish. More information about this file is available in the CVS manual. Note that the -t and -f options do not work correctly with client/server CVS. edithook - this file is not used any more, but kept for historic reasons. You can safely remove this file. editinfo - CVS uses this file for editor overrides. FreeBSD does not use this functionality, as parsing the log message is done by verifymsg and logcheck. This is because the editinfo functionality does not work properly with remote commits, or ones that use the -m or -F options. You should not have to touch this file. exclude - this file lists regular expressions that are used by commit_prep.pl to determine files which cannot contain a revision header. In the FreeBSD setup, all files under revision control need to have a revision header (like $FreeBSD$). All filenames that match one of the lines in this file are exempted from this check. You should add expressions to this file as you checkin files that cannot have a revision header. For the purpose of installing the scripts, it may be best to exclude CVSROOT/ from header checks. log_accum.pl - this is a script that takes the log message as provided by the logcheck script, and appends it to a log file in the repository for backup purposes. It also handles mailing out a message to an email address you provide (in cfg_local.pm). It hooks into CVS via loginfo. You should not have to touch this file. logcheck - this file parses the commit log message that committers provide, and attempts to sanitize it somewhat. It hooks into CVS via verifymsg. You should not have to touch this file. This script depends on a local FreeBSD hack of CVS: this version reads the log message back in after this script has modified it. The stock version of CVS does not do this which makes logcheck unable to clean up the log message, although it is still able to check that it is syntactically OK. CVS 1.11.2 can be configured to have the same behaviour as FreeBSD's version by setting RereadLogAfterVerify=always in the config file. loginfo - this file is used by CVS to control where log information is sent; log_accum.pl hooks in here. You should not have to touch this file. modules - this file retains its traditional meaning in CVS. You should remove the FreeBSD modules from the stock version. You can edit this as you wish. More information about this file is available in the CVS manual. notify - this file is used by CVS in case someone sets a watch on a file. It is not used in the FreeBSD repository. You can edit this as you wish. More information about this file is available in the CVS manual. options - this file is specific to the FreeBSD version of CVS, and is also supported by the Debian version. It contains the keyword to expand in revision headers. You should alter this to match the keyword you specified in cfg_local.pm (if you use that feature, which is FreeBSD specific for now). rcsinfo - this file maps directories in the repository to template files such as rcstemplate. By default, FreeBSD uses one template for the whole repository. You can add others to this file if you wish. rcstemplate - this file is the actual template committers will see when they make a checkin. You should edit this to describe the various extra parameters you defined in cfg_local.pm. tagcheck - this files controls access to tagging in the repository. The stock FreeBSD version disallows tags with names of RELENG*, because of the release engineering process. You should edit this file as desired. taginfo - this file maps tag operations on repository directories to access control scripts such as tagcheck. You should not have to touch this file. unwrap - this script can be used to automatically unwrap binary files (see cvswrappers) on checkout. It is not used in the current FreeBSD setup because the functionality it hooks into does not work well with remote commits. You should not have to touch this file. verifymsg - this file maps repository directories to post processor scripts of log messages such as logcheck. You should not have to touch this file. wrap - this script can be used to automatically wrap binary files (see cvswrappers) on checkin. It is not used in the current FreeBSD setup because the functionality it hooks into does not work well with remote commits. You should not have to touch this file. Customizing the scripts - The next step is to setup the scripts so that they work in + The next step is to set up the scripts so that they work in your environment. You should go over all files in the directory and make your customizations. In particular, you might want to do edit the following files: If you do not wish to use the FreeBSD specific features of the scripts, you can safely remove the access file: &prompt.user; cvs rm -f access Edit avail to contain the various repository directories in which you want to control access. Make sure you retain the avail||CVSROOT line, otherwise you will lock yourself out in the next step. The other thing you can add in this file are committer groups. By default, FreeBSD uses the access file to list all its committers in, but you can use any file you wish. You can also add groups if you want (the syntax is specified at the top of cvs_acls.pl). Edit cfg_local.pm to contain the options you want. In particular, you should take a look at the following configurable items: %TEMPLATE_HEADERS - these get processed by the log scripts, and inserted below the commit mail if present and non-empty in the commit message. You can probably remove the PR and MFC after entries. And of course you can add your own. $MAIL_BRANCH_HDR - if you want to insert a header into each commit mail describing the branch on which the commit was made, define this to match your setup. Or leave it empty if you do not want such a header. @COMMIT_HOSTS - define this to be a list of hosts on which people can commit. $MAILADDRS - set this to the admin or list address that should receive commit mail. @LOG_FILE_MAP - change this array as you wish - each regexp is matched on the directory of the commit, and the commit log message gets stored in the commitlogs subdirectory in the filename mentioned. $COMMITCHECK_EXTRA - if you do not want to use the FreeBSD specific access checks, you should remove the definition of $COMMITCHECK_EXTRA from this file. Changing the $IDHEADER parameter is only guaranteed to work on FreeBSD platforms; it depends on FreeBSD specific modifications to CVS. You can check cfg.pm to see which other options can be changed, but the above is a reasonable subset. Edit exclude to remove the FreeBSD specific entries (such as all lines beginning with ^ports/ etc.). Furthermore, comment out the lines beginning with ^CVSROOT/, and add one line with only ^CVSROOT/ on it. After the wrapper is installed, you can add your header to the files in the CVSROOT directory and restore these lines, but for now they will only be in the way when you try to commit later on. Edit modules, and delete all FreeBSD stuff. Add your own modules if you wish. This step is only necessary if you specified a value for $IDHEADER in cfg_local.pm (which only works using a FreeBSD modified CVS). Edit options to match the tag you specified in cfg_local.pm. A global search and replace of FreeBSD with your tag should suffice. Edit rcstemplate to contain the same keywords as specified in cfg_local.pm. Optionally remove the FreeBSD checks from tagcheck. You can simply add exit 0 to the top of the file to disable all checks on tagging. The last thing to do before you are finished, is to make sure the commitlogs can be stored. By default these are stored in the repository, in the commitlogs subdirectory of the CVSROOT directory. This directory needs to be created, so do the following: &prompt.user; mkdir commitlogs &prompt.user; cvs add commitlogs Now, after careful review, you should commit your changes. Be sure that you have granted yourself access to the CVSROOT directory in your avail before you do this, because otherwise you will lock yourself out. So make sure everything is as you intend, and then do the following: &prompt.user; cvs commit -m '- Initial FreeBSD scripts commit' Testing the setup You are ready for the first test: a forced commit to the avail file, to make sure everything works as expected. &prompt.user; cvs commit -f -m 'Forced commit to test the new CVSROOT scripts' avail If everything works, congratulations! You now have a working setup of the FreeBSD scripts for your repository. If CVS still complains about something, go back and recheck if all of the above steps have been performed correctly. FreeBSD specific setup The FreeBSD project itself uses a slightly different setup, which also uses files from the freebsd subdirectory of the FreeBSD CVSROOT. The project uses this because of the large number of committers, which all would have to be in the same group. So, a simple wrapper was written which ensures that people have the correct credentials to commit, and then sets the group id to that of the repository. If your repository also needs this, the steps to set this up are documented below. But first an overview of the files involved. Files used in the FreeBSD setup access - this file controls access information. You should edit this file to include all members of your project. freebsd/commitmail.pl - this file is not used any more, but kept for historic reasons. You should not have to touch this file. freebsd/cvswrap.c - this is the source to the CVS wrapper that you will need to install to make all access checks actually work. More information on this below. You should edit the paths in the ACCESS and REALCVS macros to match your setup. freebsd/mailsend.c - this file is needed by the FreeBSD setup of the mailing lists. You should not have to touch this file. The procedure Edit the access file to contain only your username. Edit cvswrap.c to contain the correct path for your setup. This is defined in a macro named ACCESS. You should also change the location of the real cvs binary if it is not appropriate to your situation. The stock cvswrap.c expects to be a replacement for the systemwide cvs command, which will be moved to /usr/bin/ncvs. My copy of cvswrap.c has this: #define ACCESS "/local/cvsroot/CVSROOT/access" #define REALCVS "/usr/bin/ncvs" Next up is installing the wrapper to ensure you become the correct group when committing. The sources for this live in cvswrap.c in your CVSROOT. Compile the sources that you edited to include the correct paths: &prompt.user; cc -o cvs cvswrap.c And then install them (you have to be root for this step): &prompt.root; mv /usr/bin/cvs /usr/bin/ncvs &prompt.root; mv cvs /usr/bin/cvs &prompt.root; chown root:ncvs /usr/bin/cvs /usr/bin/ncvs &prompt.root; chmod o-rx /usr/bin/ncvs &prompt.root; chmod u-w,g+s /usr/bin/cvs This installs the wrapper as the default cvs command, making sure that anyone who wants to use the repository has to have the correct access levels. You can now remove everyone from your repository group. All access control is done by your wrapper, and this wrapper will set the correct group for access. Testing the setup Your wrapper should now be setup. You can of course test this by making a forced commit to the access file: &prompt.user; cvs commit -f -m 'Forced commit to test the new CVSROOT scripts' access Again, if this fails, check to see whether all of the above steps have been executed correctly.
diff --git a/en_US.ISO8859-1/articles/dialup-firewall/article.sgml b/en_US.ISO8859-1/articles/dialup-firewall/article.sgml index 1bc1775ce6..99694b973b 100644 --- a/en_US.ISO8859-1/articles/dialup-firewall/article.sgml +++ b/en_US.ISO8859-1/articles/dialup-firewall/article.sgml @@ -1,389 +1,389 @@ %man; %trademarks; ]>
Dialup firewalling with FreeBSD Marc Silver
marcs@draenor.org
 $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.general; - This article documents how to setup a firewall using a PPP + This article documents how to set up a firewall using a PPP dialup with FreeBSD and IPFW, and specifically with firewalling over a dialup with a dynamically assigned IP address. This document does not cover setting up your PPP connection in the first place. Preface Dialup Firewalling with FreeBSD - This document covers the process that is required to setup + This document covers the process that is required to set up firewalling with FreeBSD when an IP address is assigned dynamically by your ISP. While every effort has been made to make this document as informative and correct as possible, you are welcome to mail your comments/suggestions to the marcs@draenor.org. Kernel Options The first thing you will need to do is recompile your kernel. If you need more information on how to recompile the kernel, then the best place to start is the kernel configuration section in the Handbook. You need to add the following options into your kernel configuration file: options IPFIREWALL Enables the kernel's firewall code. options IPFW2 Enables the new version of IPFW. Only do this if you're running FreeBSD 4.X, this is the default in newer versions of FreeBSD. options IPFIREWALL_VERBOSE Sends logged packets to the system logger. options IPFIREWALL_VERBOSE_LIMIT=100 Limits the number of times a matching entry is logged. This prevents your log file from filling up with lots of repetitive entries. 100 is a reasonable number to use, but you can adjust it based on your requirements. options IPDIVERT Enables divert sockets, which will be shown later. There are some other optional items that you can compile into the kernel for some added security. These are not required in order to get firewalling to work, but some more paranoid users may want to use them. options TCP_DROP_SYNFIN This option ignores TCP packets with SYN and FIN. This prevents tools like security/nmap from identifying the TCP/IP stack of the machine, but breaks support for RFC1644 extensions. This is not recommended if the machine will be running a web server. Do not reboot once you have recompiled the kernel. Hopefully, we will only need to reboot once to complete the installation of the firewall. Changing <filename>/etc/rc.conf</filename> to load the firewall We now need to make some changes to /etc/rc.conf in order to tell it about the firewall. Simply add the following lines: firewall_enable="YES" firewall_script="/etc/firewall/fwrules" natd_enable="YES" natd_interface="tun0" natd_flags="-dynamic" For more information on the functions of these statements take a look at /etc/defaults/rc.conf and read &man.rc.conf.5; Disable PPP's network address translation You may already be using PPP's built in network address translation (NAT). If that is the case then you will have to disable it, as these examples use &man.natd.8; to do the same. If you already have a block of entries to automatically start PPP, it probably looks like this: ppp_enable="YES" ppp_mode="auto" ppp_nat="YES" ppp_profile="profile" If so, you will need to specifically disable ppp_nat by making sure you have ppp_nat="NO" in /etc/rc.conf. You will also need to remove any nat enable yes or alias enable yes in /etc/ppp/ppp.conf. The rule set for the firewall We are nearly done now. All that remains now is to define the firewall rules and then we can reboot and the firewall should be up and running. I realize that everyone will want something slightly different when it comes to their rule base. What I have tried to do is write a rule base that suits most dialup users. You can obviously modify it to your needs by using the following rules as the foundation for your own rule base. First, let's start with the basics of closed firewalling. What you want to do is deny everything by default and then only open up for the things you really need. Rules should be in the order of allow first and then deny. The premise is that you add the rules for your allows, and then everything else is denied. :) Now, let's make the dir /etc/firewall. Change into the directory and edit the file fwrules as we specified in rc.conf. Please note that you can change this filename to anything you wish. This guide just gives an example of a filename. Now, let's look at a sample firewall file, that is commented nicely. # Define the firewall command (as in /etc/rc.firewall) for easy # reference. Helps to make it easier to read. fwcmd="/sbin/ipfw" # Force a flushing of the current rules before we reload. $fwcmd -f flush # Divert all packets through the tunnel interface. $fwcmd add divert natd all from any to any via tun0 # Allow all connections that have dynamic rules built for them, # but deny established connections that don't have a dynamic rule. # See ipfw(8) for details. $fwcmd add check-state $fwcmd add deny tcp from any to any established # Allow all localhost connections $fwcmd add allow tcp from me to any out via lo0 setup keep-state $fwcmd add deny tcp from me to any out via lo0 $fwcmd add allow ip from me to any out via lo0 keep-state # Allow all connections from my network card that I initiate $fwcmd add allow tcp from me to any out xmit any setup keep-state $fwcmd add deny tcp from me to any $fwcmd add allow ip from me to any out xmit any keep-state # Everyone on the Internet is allowed to connect to the following # services on the machine. This example specifically allows connections # to sshd and a webserver. $fwcmd add allow tcp from any to me dst-port 22,80 in recv any setup keep-state # This sends a RESET to all ident packets. $fwcmd add reset log tcp from any to me 113 in recv any # Enable ICMP: remove type 8 if you don't want your host to be pingable $fwcmd add allow icmp from any to any icmptypes 0,3,8,11,12,13,14 # Deny all the rest. $fwcmd add deny log ip from any to any You now have a fully functional firewall that will allow on connections to ports 22 and 80 and will log any other connection attempts. Now, you should be able to safely reboot and your firewall should come up fine. If you find this incorrect in anyway or experience any problems, or have any suggestions to improve this page, please email me. Questions Why are you using &man.natd.8; and &man.ipfw.8; when you could be using the built in &man.ppp.8; filters? I will have to be honest and say there is no definitive reason why I use ipfw and natd instead of the built in ppp filters. From the discussions I have had with people the consensus seems to be that while ipfw is certainly more powerful and more configurable than the ppp filters, what it makes up for in functionality it loses in being easy to customize. One of the reasons I use it is because I prefer firewalling to be done at a kernel level rather than by a userland program. I get messages like limit 100 reached on entry 2800 and after that I never see more denies in my logs. Is my firewall still working? This merely means that the maximum logging count for the rule has been reached. The rule itself is still working, but it will no longer log until such time as you reset the logging counters. You can reset the logging counters with the ipfw resetlog command. Alternatively, you may increase the log limit in your kernel configuration with the option as described above. You may also change this limit (without recompiling your kernel and having to reboot) by using the net.inet.ip.fw.verbose_limit &man.sysctl.8; value. If I am using private addresses internally, such as in the 192.168.0.0 range, could I add a command like $fwcmd add deny all from any to 192.168.0.0:255.255.0.0 via tun0 to the firewall rules to prevent outside attempts to connect to internal machines? The simple answer is no. The reason for this is that natd is doing address translation for anything being diverted through the tun0 device. As far as it is concerned incoming packets will speak only to the dynamically assigned IP address and not to the internal network. Note though that you can add a rule like $fwcmd add deny all from 192.168.0.4:255.255.0.0 to any via tun0 which would limit a host on your internal network from going out via the firewall. There must be something wrong. I followed your instructions to the letter and now I am locked out. This tutorial assumes that you are running userland-ppp, therefore the supplied rule set operates on the tun0 interface, which corresponds to the first connection made with &man.ppp.8; (a.k.a. user-ppp). Additional connections would use tun1, tun2 and so on. You should also note that &man.pppd.8; uses the ppp0 interface instead, so if you start the connection with &man.pppd.8; you must substitute tun0 for ppp0. A quick way to edit the firewall rules to reflect this change is shown below. The original rule set is backed up as fwrules_tun0. &prompt.user; cd /etc/firewall /etc/firewall&prompt.user; su Password: /etc/firewall&prompt.root; mv fwrules fwrules_tun0 /etc/firewall&prompt.root; cat fwrules_tun0 | sed s/tun0/ppp0/g > fwrules To know whether you are currently using &man.ppp.8; or &man.pppd.8; you can examine the output of &man.ifconfig.8; once the connection is up. E.g., for a connection made with &man.pppd.8; you would see something like this (showing only the relevant lines): &prompt.user; ifconfig (skipped...) ppp0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1524 inet xxx.xxx.xxx.xxx --> xxx.xxx.xxx.xxx netmask 0xff000000 (skipped...) On the other hand, for a connection made with &man.ppp.8; (user-ppp) you should see something similar to this: &prompt.user; ifconfig (skipped...) ppp0: flags=8010<POINTOPOINT,MULTICAST> mtu 1500 (skipped...) tun0: flags=8051<UP,POINTOPOINT,RUNNING,MULTICAST> mtu 1524 (IPv6 stuff skipped...) inet xxx.xxx.xxx.xxx --> xxx.xxx.xxx.xxx netmask 0xffffff00 Opened by PID xxxxx (skipped...)
diff --git a/en_US.ISO8859-1/articles/diskless-x/article.sgml b/en_US.ISO8859-1/articles/diskless-x/article.sgml index 07cf5af4f6..061a0089b7 100644 --- a/en_US.ISO8859-1/articles/diskless-x/article.sgml +++ b/en_US.ISO8859-1/articles/diskless-x/article.sgml @@ -1,362 +1,362 @@ %man; %trademarks; ]>
Diskless X Server: a how to guide Jerry Kendall
jerry@kcis.com
28-December-1996 1996 Jerry Kendall &tm-attrib.freebsd; &tm-attrib.3com; &tm-attrib.microsoft; &tm-attrib.sun; &tm-attrib.general; With the help of some friends on the FreeBSD-hackers list, I have been able to create a diskless X terminal. The creation of the X terminal required first creating a diskless system with minimal utilities mounted via NFS. These same steps were used to create 2 separate diskless systems. The first is altair.example.com. A diskless X terminal that I run on my old 386DX-40. It has a 340Meg hard disk but, I did not want to change it. So, it boots from antares.example.com across a Ethernet. The second - system is a 486DX2-66. I setup a diskless FreeBSD (complete) that + system is a 486DX2-66. I set up a diskless FreeBSD (complete) that uses no local disk. The server in that case is a Sun 670MP running &sunos; 4.1.3. The same setup configuration was needed for both. I am sure that there is stuff that needs to be added to this. Please send me any comments. Creating the boot floppy (On the diskless system) Since the network boot loaders will not work with some of the TSR's and such that &ms-dos; uses, it is best to create a dedicated boot floppy or, if you can, create an &ms-dos; menu that will (via the config.sys/autoexec.bat files) ask what configuration to load when the system starts. The later is the method that I use and it works great. My &ms-dos; (6.x) menu is below. <filename>config.sys</filename> [menu] menuitem=normal, normal menuitem=unix, unix [normal] .... normal config.sys stuff ... [unix] <filename>autoexec.bat</filename> @ECHO OFF goto %config% :normal ... normal autoexec.bat stuff ... goto end :unix cd \netboot nb8390.com :end Getting the network boot programs (On the server) Compile the net-boot programs that are located in /usr/src/sys/i386/boot/netboot. You should read the comments at the top of the Makefile. Adjust as required. Make a backup of the original in case it gets foobar'd. When the build is done, there should be 2 &ms-dos; executables, nb8390.com and nb3c509.com. One of these two programs will be what you need to run on the diskless server. It will load the kernel from the boot server. At this point, put both programs on the &ms-dos; boot floppy created earlier. Determine which program to run (On the diskless system) If you know the chipset that your Ethernet adapter uses, this is easy. If you have the NS8390 chipset, or a NS8390 based chipset, use nb8390.com. If you have a &tm.3com; 509 based chipset, use the nb3C509.com boot program. If you are not sure which you have, try using one, if it says No adapter found, try the other. Beyond that, you are pretty much on your own. Booting across the network Boot the diskless system with out any config.sys/autoexec.bat files. Try running the boot program for your Ethernet adapter. My Ethernet adapter is running in WD8013 16bit mode so I run nb8390.com C:> cd \netboot C:> nb8390 Boot from Network (Y/N) ? Y BOOTP/TFTP/NFS bootstrap loader ESC for menu Searching for adapter.. WD8013EBT base 0x0300, memory 0x000D8000, addr 00:40:01:43:26:66 Searching for server... At this point, my diskless system is trying to find a machine to act as a boot server. Make note of the addr line above, you will need this number later. Reset the diskless system and modify your config.sys and autoexec.bat files to do these steps automatically for you. Perhaps in a menu. If you had to run nb3c509.com instead of nb8390.com the output is the same as above. If you got No adapter found at the Searching for adapter... message, verify that you did indeed set the compile time defines in the Makefile correctly. Allowing systems to boot across the network (On the server) Make sure the /etc/inetd.conf file has entries for tftp and bootps. Mine are listed below: tftp dgram udp wait nobody /usr/libexec/tftpd tftpd /tftpboot # # Additions by who ever you are bootps dgram udp wait root /usr/libexec/bootpd bootpd /etc/bootptab If you have to change the /etc/inetd.conf file, send a HUP signal to &man.inetd.8;. To do this, get the process ID of inetd with ps -ax | grep inetd | grep -v grep. Once you have it, send it a HUP signal. Do this by kill -HUP <pid>. This will force inetd to re-read its config file. Did you remember to note the addr line from the output of the boot loader on the diskless system? Guess what, here is where you need it. Add an entry to /etc/bootptab (maybe creating the file). It should be laid out identical to this: altair:\ :ht=ether:\ :ha=004001432666:\ :sm=255.255.255.0:\ :hn:\ :ds=199.246.76.1:\ :ip=199.246.76.2:\ :gw=199.246.76.1:\ :vm=rfc1048: The lines are as follows: altair the diskless systems name without the domain name. ht=ether the hardware type of ethernet. ha=004001432666 the hardware address (the number noted above). sm=255.255.255.0 the subnet mask. hn tells server to send client's hostname to the client. ds=199.246.76.1 tells the client who the domain server is. ip=199.246.76.2 tells the client what its IP address is. gw=199.246.76.1 tells the client what the default gateway is. vm=... just leave it there. - Be sure to setup the IP addresses correctly, the addresses above + Be sure to set up the IP addresses correctly, the addresses above are my own. Create the directory /tftpboot on the server it will contain the configuration files for the diskless systems that the server will serve. These files will be named cfg.ip where ip is the IP address of the diskless system. The config file for altair is /tftpboot/cfg.199.246.76.2. The contents is: rootfs 199.246.76.1:/DiskLess/rootfs/altair hostname altair.example.com The line hostname altair.example.com simply tells the diskless system what its fully qualified domain name is. The line rootfs 199.246.76.1:/DiskLess/rootfs/altair tells the diskless system where its NFS mountable root filesystem is located. The NFS mounted root filesystem will be mounted read only. The hierarchy for the diskless system can be re-mounted allowing read-write operations if required. I use my spare 386DX-40 as a dedicated X terminal. The hierarchy for altair is: / /bin /etc /tmp /sbin /dev /dev/fd /usr /var /var/run The actual list of files is: -r-xr-xr-x 1 root wheel 779984 Dec 11 23:44 ./kernel -r-xr-xr-x 1 root bin 299008 Dec 12 00:22 ./bin/sh -rw-r--r-- 1 root wheel 499 Dec 15 15:54 ./etc/rc -rw-r--r-- 1 root wheel 1411 Dec 11 23:19 ./etc/ttys -rw-r--r-- 1 root wheel 157 Dec 15 15:42 ./etc/hosts -rw-r--r-- 1 root bin 1569 Dec 15 15:26 ./etc/XF86Config.altair -r-x------ 1 bin bin 151552 Jun 10 1995 ./sbin/init -r-xr-xr-x 1 bin bin 176128 Jun 10 1995 ./sbin/ifconfig -r-xr-xr-x 1 bin bin 110592 Jun 10 1995 ./sbin/mount_nfs -r-xr-xr-x 1 bin bin 135168 Jun 10 1995 ./sbin/reboot -r-xr-xr-x 1 root bin 73728 Dec 13 22:38 ./sbin/mount -r-xr-xr-x 1 root wheel 1992 Jun 10 1995 ./dev/MAKEDEV.local -r-xr-xr-x 1 root wheel 24419 Jun 10 1995 ./dev/MAKEDEV If you are not using &man.devfs.5; (which is the default in FreeBSD 5.X), you should make sure that you do not forget to run MAKEDEV all in the dev directory. My /etc/rc for altair is: #!/bin/sh # PATH=/bin:/ export PATH # # configure the localhost /sbin/ifconfig lo0 127.0.0.1 # # configure the ethernet card /sbin/ifconfig ed0 199.246.76.2 netmask 0xffffff00 # # mount the root filesystem via NFS /sbin/mount antares:/DiskLess/rootfs/altair / # # mount the /usr filesystem via NFS /sbin/mount antares:/DiskLess/usr /usr # /usr/X11R6/bin/XF86_SVGA -query antares -xf86config /etc/XF86Config.altair > /dev/null 2>&1 # # Reboot after X exits /sbin/reboot # # We blew up.... exit 1 Any comments and all questions welcome.
diff --git a/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_1.sh b/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_1.sh index 472a0d2c45..35198d8fc3 100644 --- a/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_1.sh +++ b/en_US.ISO8859-1/articles/fbsd-from-scratch/stage_1.sh @@ -1,228 +1,228 @@ #!/bin/sh # # stage_1.sh - FreeBSD From Scratch, Stage 1: System Installation. # Usage: ./stage_1.sh # # $FreeBSD$ set -x -e PATH=/bin:/usr/bin:/sbin:/usr/sbin # Prerequisites: # # a) Successfully completed "make buildworld" and "make buildkernel" # b) Unused partitions (at least one for the root fs, probably more for # the new /usr and /var, to your liking.) # Root mount point where you create the new system. Because it is only # used as a mount point, no space will be used on that file system as all # files are of course written to the mounted file system(s). DESTDIR=/newroot SRC=/usr/src # Where your src tree is. # ---------------------------------------------------------------------------- # # Step 1: Create an empty directory tree below $DESTDIR. # ---------------------------------------------------------------------------- # step_one () { # The new root file system. Mandatory. # Change device names (DEV_*) or risk foot shooting. DEV_ROOT=/dev/da3s1a mkdir -p ${DESTDIR} newfs ${DEV_ROOT} tunefs -n enable ${DEV_ROOT} mount -o noatime ${DEV_ROOT} ${DESTDIR} # Additional file systems and initial mount points. Optional. DEV_VAR=/dev/vinum/var_a newfs ${DEV_VAR} tunefs -n enable ${DEV_VAR} mkdir -m 755 ${DESTDIR}/var mount -o noatime ${DEV_VAR} ${DESTDIR}/var DEV_USR=/dev/vinum/usr_a newfs ${DEV_USR} tunefs -n enable ${DEV_USR} mkdir -m 755 ${DESTDIR}/usr mount -o noatime ${DEV_USR} ${DESTDIR}/usr mkdir -m 755 -p ${DESTDIR}/usr/ports mount /dev/vinum/ports ${DESTDIR}/usr/ports # Now create all the other directories. Mandatory. cd ${SRC}/etc; make distrib-dirs DESTDIR=${DESTDIR} # My personal preference is to symlink tmp -> var/tmp. Optional. cd ${DESTDIR}; rmdir tmp; ln -s var/tmp } # ---------------------------------------------------------------------------- # # Step 2: Fill the empty /etc directory tree and put a few files in /. # ---------------------------------------------------------------------------- # step_two () { # Add or remove from this list at your discretion. Mostly mandatory. for f in \ /.profile \ /etc/group \ /etc/hosts \ /etc/inetd.conf \ /etc/ipfw.conf \ /etc/make.conf \ /etc/master.passwd \ /etc/nsswitch.conf \ /etc/ntp.conf \ /etc/printcap \ /etc/profile \ /etc/rc.conf \ /etc/resolv.conf \ /etc/start_if.xl0 \ /etc/ttys \ /etc/ppp/* \ /etc/mail/aliases \ /etc/mail/aliases.db \ /etc/mail/hal9000.mc \ /etc/mail/service.switch \ /etc/ssh/*key* \ /etc/ssh/*_config \ /etc/X11/XF86Config-4 \ /boot/splash.bmp \ /boot/loader.conf \ /boot/device.hints ; do cp -p ${f} ${DESTDIR}${f} done # Delete mergemaster's temproot, if any. TEMPROOT=/var/tmp/temproot.stage1 if test -d ${TEMPROOT}; then chflags -R 0 ${TEMPROOT} rm -rf ${TEMPROOT} fi mergemaster -i -m ${SRC}/etc -t ${TEMPROOT} -D ${DESTDIR} cap_mkdb ${DESTDIR}/etc/login.conf pwd_mkdb -d ${DESTDIR}/etc -p ${DESTDIR}/etc/master.passwd # Mergemaster does not create empty files, e.g. in /var/log. Do so now, # but do not clobber files that may have been copied in the loop above. cd ${TEMPROOT} find . -type f | sed 's,^\./,,' | while read f; do if test -r ${DESTDIR}/${f}; then echo "${DESTDIR}/${f} already exists; not copied" else echo "Creating empty ${DESTDIR}/${f}" cp -p ${f} ${DESTDIR}/${f} fi done chflags -R 0 ${TEMPROOT} rm -rf ${TEMPROOT} } # ---------------------------------------------------------------------------- # # Step 3: Install world. # ---------------------------------------------------------------------------- # step_three () { cd ${SRC} make installworld DESTDIR=${DESTDIR} } # ---------------------------------------------------------------------------- # # Step 4: Install kernel and modules. # ---------------------------------------------------------------------------- # step_four () { cd ${SRC} # The loader.conf and device.hints are required by the installkernel target. # If you have not copied them in Step 2, cp them as shown in the next 2 lines. # cp sys/boot/forth/loader.conf ${DESTDIR}/boot/defaults # cp sys/i386/conf/GENERIC.hints ${DESTDIR}/boot/device.hints make installkernel DESTDIR=${DESTDIR} KERNCONF=HAL9000 } # ---------------------------------------------------------------------------- # # Step 5: Install or modify a few essential files. # ---------------------------------------------------------------------------- # step_five () { # Create /etc/fstab; mandatory. Modify to match your devices. cat <${DESTDIR}/etc/fstab # Device Mountpoint FStype Options Dump Pass# /dev/da3s1b none swap sw 0 0 /dev/da4s2b none swap sw 0 0 /dev/da3s1a / ufs rw 1 1 /dev/da1s2a /src ufs rw 0 2 /dev/da2s2f /share ufs rw 0 2 /dev/vinum/var_a /var ufs rw 0 2 /dev/vinum/usr_a /usr ufs rw 0 2 /dev/vinum/home /home ufs rw 0 2 /dev/vinum/ncvs /home/ncvs ufs rw,noatime 0 2 /dev/vinum/ports /usr/ports ufs rw,noatime 0 2 # /dev/cd0 /dvd cd9660 ro,noauto 0 0 /dev/cd1 /cdrom cd9660 ro,noauto 0 0 proc /proc procfs rw 0 0 EOF # More directories; optional. mkdir -m 755 -p ${DESTDIR}/src; chown root:wheel ${DESTDIR}/src mkdir -m 755 -p ${DESTDIR}/share; chown root:wheel ${DESTDIR}/share mkdir -m 755 -p ${DESTDIR}/dvd; chown root:wheel ${DESTDIR}/dvd mkdir -m 755 -p ${DESTDIR}/home; chown root:wheel ${DESTDIR}/home mkdir -m 755 -p ${DESTDIR}/usr/ports; chown root:wheel ${DESTDIR}/usr/ports - # Setup time zone info; pretty much mandatory. + # Set up time zone info; pretty much mandatory. cp ${DESTDIR}/usr/share/zoneinfo/Europe/Berlin ${DESTDIR}/etc/localtime if test -r /etc/wall_cmos_clock; then cp -p /etc/wall_cmos_clock ${DESTDIR}/etc/wall_cmos_clock fi } # ---------------------------------------------------------------------------- # # Step 6: Things important to me when I first login to a new system. # NOTE: Do not install too many binaries here. With the old system running and # the new binaries and headers installed you are likely to run into bootstrap # problems. Ports should be compiled after you have booted in the new system. # ---------------------------------------------------------------------------- # step_six () { chroot ${DESTDIR} sh -c "cd /usr/ports/shells/zsh; make clean install clean" chroot ${DESTDIR} sh -c "cd /etc/mail; make install" # configure sendmail # Without the compat symlink the linux_base files end up on the root fs: cd ${DESTDIR}; mkdir -m 755 usr/compat chown root:wheel usr/compat; ln -s usr/compat mkdir -m 755 usr/compat/linux mkdir -m 755 boot/grub # Make spooldirs for the printers in my /etc/printcap. cd ${DESTDIR}/var/spool/output/lpd; mkdir -p as od ev te lp da touch ${DESTDIR}/var/log/lpd-errs # More files I want to inherit from the old system. for f in \ /var/cron/tabs/root \ /var/mail/* \ /boot/grub/*; do cp -p ${f} ${DESTDIR}${f} done # If you do not have /home on a shared partition, you may want to copy it: # mkdir -p ${DESTDIR}/home # cd /home; tar cf - . | (cd ${DESTDIR}/home; tar xpvf -) # Starting with FreeBSD 5.x, perl lives in /usr/local/bin but many scripts # use a hardcoded #!/usr/bin/perl; use a symlink to make them work. cd ${DESTDIR}/usr/bin; ln -s ../local/bin/perl cd ${DESTDIR}/usr; rmdir src; ln -s ../src/current src } do_steps () { step_one step_two step_three step_four step_five step_six } do_steps 2>&1 | tee stage_1.log # EOF $RCSfile: stage_1.sh,v $ vim: tabstop=2:expandtab: diff --git a/en_US.ISO8859-1/articles/fonts/article.sgml b/en_US.ISO8859-1/articles/fonts/article.sgml index 65ee58269b..ec361445f0 100644 --- a/en_US.ISO8859-1/articles/fonts/article.sgml +++ b/en_US.ISO8859-1/articles/fonts/article.sgml @@ -1,983 +1,983 @@ %freebsd; %man; %trademarks; ]>
Fonts and FreeBSD A Tutorial Dave Bodenstab
imdave@synet.net
Wed Aug 7, 1996 &tm-attrib.freebsd; &tm-attrib.adobe; &tm-attrib.apple; &tm-attrib.linux; &tm-attrib.microsoft; &tm-attrib.opengroup; &tm-attrib.general; This document contains a description of the various font files that may be used with FreeBSD and the syscons driver, X11, Ghostscript and Groff. Cookbook examples are provided for switching the syscons display to 80x60 mode, and for using type 1 fonts with the above application programs. Introduction There are many sources of fonts available, and one might ask how they might be used with FreeBSD. The answer can be found by carefully searching the documentation for the component that one would like to use. This is very time consuming, so this tutorial is an attempt to provide a shortcut for others who might be interested. Basic terminology There are many different font formats and associated font file suffixes. A few that will be addressed here are: .pfa, .pfb &postscript; type 1 fonts. The .pfa is the Ascii form and .pfb the Binary form. .afm The font metrics associated with a type 1 font. .pfm The printer font metrics associated with a type 1 font. .ttf A &truetype; font .fot An indirect reference to a TrueType font (not an actual font) .fon, .fnt Bitmapped screen fonts The .fot file is used by &windows; as sort of a symbolic link to the actual &truetype; font (.ttf) file. The .fon font files are also used by Windows. I know of no way to use this font format with FreeBSD. What font formats can I use? Which font file format is useful depends on the application being used. FreeBSD by itself uses no fonts. Application programs and/or drivers may make use of the font files. Here is a small cross reference of application/driver to the font type suffixes: Driver syscons .fnt Application Ghostscript .pfa, .pfb, .ttf X11 .pfa, .pfb Groff .pfa, .afm Povray .ttf The .fnt suffix is used quite frequently. I suspect that whenever someone wanted to create a specialized font file for their application, more often than not they chose this suffix. Therefore, it is likely that files with this suffix are not all the same format; specifically, the .fnt files used by syscons under FreeBSD may not be the same format as a .fnt file one encounters in the &ms-dos;/&windows; environment. I have not made any attempt at using other .fnt files other than those provided with FreeBSD. Setting a virtual console to 80x60 line mode First, an 8x8 font must be loaded. To do this, /etc/rc.conf should contain the line (change the font name to an appropriate one for your locale): font8x8="iso-8x8" # font 8x8 from /usr/share/syscons/fonts/* (or NO). The command to actually switch the mode is &man.vidcontrol.1;: &prompt.user; vidcontrol VGA_80x60 Various screen-oriented programs, such as &man.vi.1;, must be able to determine the current screen dimensions. As this is achieved this through ioctl calls to the console driver (such as &man.syscons.4;) they will correctly determine the new screen dimensions. To make this more seamless, one can embed these commands in the startup scripts so it takes place when the system boots. To do this is add this line to /etc/rc.conf allscreens_flags="VGA_80x60" # Set this vidcontrol mode for all virtual screens References: &man.rc.conf.5;, &man.vidcontrol.1;. Using type 1 fonts with X11 X11 can use either the .pfa or the .pfb format fonts. The X11 fonts are located in various subdirectories under /usr/X11R6/lib/X11/fonts. Each font file is cross referenced to its X11 name by the contents of the fonts.dir file in each directory. There is already a directory named Type1. The most straight forward way to add a new font is to put it into this directory. A better way is to keep all new fonts in a separate directory and use a symbolic link to the additional font. This allows one to more easily keep track of ones fonts without confusing them with the fonts that were originally provided. For example: Create a directory to contain the font files &prompt.user; mkdir -p /usr/local/share/fonts/type1 &prompt.user; cd /usr/local/share/fonts/type1 Place the .pfa, .pfb and .afm files here One might want to keep readme files, and other documentation for the fonts here also &prompt.user; cp /cdrom/fonts/atm/showboat/showboat.pfb . &prompt.user; cp /cdrom/fonts/atm/showboat/showboat.afm . Maintain an index to cross reference the fonts &prompt.user; echo showboat - InfoMagic CICA, Dec 1994, /fonts/atm/showboat >>INDEX Now, to use a new font with X11, one must make the font file available and update the font name files. The X11 font names look like: -bitstream-charter-medium-r-normal-xxx-0-0-0-0-p-0-iso8859-1 | | | | | | | | | | | | \ \ | | | | | \ \ \ \ \ \ \ +----+- character set | | | | \ \ \ \ \ \ \ +- average width | | | | \ \ \ \ \ \ +- spacing | | | \ \ \ \ \ \ +- vertical res. | | | \ \ \ \ \ +- horizontal res. | | | \ \ \ \ +- points | | | \ \ \ +- pixels | | | \ \ \ foundry family weight slant width additional style A new name needs to be created for each new font. If you have some information from the documentation that accompanied the font, then it could serve as the basis for creating the name. If there is no information, then you can get some idea by using &man.strings.1; on the font file. For example: &prompt.user; strings showboat.pfb | more %!FontType1-1.0: Showboat 001.001 %%CreationDate: 1/15/91 5:16:03 PM %%VMusage: 1024 45747 % Generated by Fontographer 3.1 % Showboat 1991 by David Rakowski. Alle Rechte Vorbehalten. FontDirectory/Showboat known{/Showboat findfont dup/UniqueID known{dup /UniqueID get 4962377 eq exch/FontType get 1 eq and}{pop false}ifelse {save true}{false}ifelse}{false}ifelse 12 dict begin /FontInfo 9 dict dup begin /version (001.001) readonly def /FullName (Showboat) readonly def /FamilyName (Showboat) readonly def /Weight (Medium) readonly def /ItalicAngle 0 def /isFixedPitch false def /UnderlinePosition -106 def /UnderlineThickness 16 def /Notice (Showboat 1991 by David Rakowski. Alle Rechte Vorbehalten.) readonly def end readonly def /FontName /Showboat def --stdin-- Using this information, a possible name might be: -type1-Showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 The components of our name are: Foundry Lets just name all the new fonts type1. Family The name of the font. Weight Normal, bold, medium, semibold, etc. From the &man.strings.1; output above, it appears that this font has a weight of medium. Slant roman, italic, oblique, etc. Since the ItalicAngle is zero, roman will be used. Width Normal, wide, condensed, extended, etc. Until it can be examined, the assumption will be normal. Additional style Usually omitted, but this will indicate that the font contains decorative capital letters. Spacing proportional or monospaced. Proportional is used since isFixedPitch is false. All of these names are arbitrary, but one should strive to be compatible with the existing conventions. A font is referenced by name with possible wild cards by an X11 program, so the name chosen should make some sense. One might begin by simply using …-normal-r-normal-…-p-… as the name, and then use &man.xfontsel.1; to examine it and adjust the name based on the appearance of the font. So, to complete our example: Make the font accessible to X11 &prompt.user; cd /usr/X11R6/lib/X11/fonts/Type1 &prompt.user; ln -s /usr/local/share/fonts/type1/showboat.pfb . Edit fonts.dir and fonts.scale, adding the line describing the font and incrementing the number of fonts which is found on the first line. &prompt.user; ex fonts.dir :1p 25 :1c 26 . :$a showboat.pfb -type1-showboat-medium-r-normal-decorative-0-0-0-0-p-0-iso8859-1 . :wq fonts.scale seems to be identical to fonts.dir… &prompt.user; cp fonts.dir fonts.scale Tell X11 that things have changed &prompt.user; xset fp rehash Examine the new font &prompt.user; xfontsel -pattern -type1-* References: &man.xfontsel.1;, &man.xset.1;, The X Windows System in a Nutshell, O'Reilly & Associates. Using type 1 fonts with Ghostscript Ghostscript references a font via its Fontmap file. This must be modified in a similar way to the X11 fonts.dir file. Ghostscript can use either the .pfa or the .pfb format fonts. Using the font from the previous example, here is how to use it with Ghostscript: Put the font in Ghostscript's font directory &prompt.user; cd /usr/local/share/ghostscript/fonts &prompt.user; ln -s /usr/local/share/fonts/type1/showboat.pfb . Edit Fontmap so Ghostscript knows about the font &prompt.user; cd /usr/local/share/ghostscript/4.01 &prompt.user; ex Fontmap :$a /Showboat (showboat.pfb) ; % From CICA /fonts/atm/showboat . :wq Use Ghostscript to examine the font &prompt.user; gs prfont.ps Aladdin Ghostscript 4.01 (1996-7-10) Copyright (C) 1996 Aladdin Enterprises, Menlo Park, CA. All rights reserved. This software comes with NO WARRANTY: see the file PUBLIC for details. Loading Times-Roman font from /usr/local/share/ghostscript/fonts/tir_____.pfb... /1899520 581354 1300084 13826 0 done. GS>Showboat DoFont Loading Showboat font from /usr/local/share/ghostscript/fonts/showboat.pfb... 1939688 565415 1300084 16901 0 done. >>showpage, press <return> to continue<< >>showpage, press <return> to continue<< >>showpage, press <return> to continue<< GS>quit References: fonts.txt in the Ghostscript 4.01 distribution Using type 1 fonts with Groff Now that the new font can be used by both X11 and Ghostscript, how can one use the new font with groff? First of all, since we are dealing with type 1 &postscript; fonts, the groff device that is applicable is the ps device. A font file must be created for each font that groff can use. A groff font name is just a file in /usr/share/groff_font/devps. With our example, the font file could be /usr/share/groff_font/devps/SHOWBOAT. The file must be created using tools provided by groff. The first tool is afmtodit. This is not normally installed, so it must be retrieved from the source distribution. I found I had to change the first line of the file, so I did: &prompt.user; cp /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.pl /tmp &prompt.user; ex /tmp/afmtodit.pl :1c #!/usr/bin/perl -P- . :wq This tool will create the groff font file from the metrics file (.afm suffix.) Continuing with our example: Many .afm files are in Mac format… ^M delimited lines We need to convert them to &unix; style ^J delimited lines &prompt.user; cd /tmp &prompt.user; cat /usr/local/share/fonts/type1/showboat.afm | tr '\015' '\012' >showboat.afm Now create the groff font file &prompt.user; cd /usr/share/groff_font/devps &prompt.user; /tmp/afmtodit.pl -d DESC -e text.enc /tmp/showboat.afm generate/textmap SHOWBOAT The font can now be referenced with the name SHOWBOAT. If ghostscript is used to drive the printers on the system, then nothing more needs to be done. However, if true PostScript printers are used, then the font must be down loaded to the printer in order for the font to be used (unless the printer happens to have the showboat font built in or on an accessible font disk.) The final step is to create a down loadable font. The pfbtops tool is used to create the .pfa format of the font, and the download file is modified to reference the new font. The download file must reference the internal name of the font. This can easily be determined from the groff font file as illustrated: Create the .pfa font file &prompt.user; pfbtops /usr/local/share/fonts/type1/showboat.pfb >showboat.pfa Of course, if the .pfa file is already available, just use a symbolic link to reference it. Get the internal font name &prompt.user; fgrep internalname SHOWBOAT internalname Showboat Tell groff that the font must be down loaded &prompt.user; ex download :$a Showboat showboat.pfa . :wq To test the font: &prompt.user; cd /tmp &prompt.user; cat >example.t <<EOF .sp 5 .ps 16 This is an example of the Showboat font: .br .ps 48 .vs (\n(.s+2)p .sp .ft SHOWBOAT ABCDEFGHI .br JKLMNOPQR .br STUVWXYZ .sp .ps 16 .vs (\n(.s+2)p .fp 5 SHOWBOAT .ft R To use it for the first letter of a paragraph, it will look like: .sp 50p \s(48\f5H\s0\fRere is the first sentence of a paragraph that uses the showboat font as its first letter. Additional vertical space must be used to allow room for the larger letter. EOF &prompt.user; groff -Tps example.t >example.ps To use ghostscript/ghostview &prompt.user; ghostview example.ps To print it &prompt.user; lpr -Ppostscript example.ps References: /usr/src/gnu/usr.bin/groff/afmtodit/afmtodit.man, &man.groff.font.5;, &man.groff.char.7;, &man.pfbtops.1;. Converting TrueType fonts to a groff/PostScript format for groff This potentially requires a bit of work, simply because it depends on some utilities that are not installed as part of the base system. They are: ttf2pf TrueType to PostScript conversion utilities. This allows conversion of a TrueType font to an ascii font metric (.afm) file. Currently available at . Note: These files are PostScript programs and must be downloaded to disk by holding down the Shift key when clicking on the link. Otherwise, your browser may try to launch ghostview to view them. The files of interest are: GS_TTF.PS PF2AFM.PS ttf2pf.ps The funny upper/lower case is due to their being intended also for DOS shells. ttf2pf.ps makes use of the others as upper case, so any renaming must be consistent with this. (Actually, GS_TTF.PS and PFS2AFM.PS are supposedly part of the ghostscript distribution, but it is just as easy to use these as an isolated utility. FreeBSD does not seem to include the latter.) You also may want to have these installed to /usr/local/share/groff_font/devps(?). afmtodit Creates font files for use with groff from ascii font metrics file. This usually resides in the directory, /usr/src/contrib/groff/afmtodit, and requires some work to get going. If you are paranoid about working in the /usr/src tree, simply copy the contents of the above directory to a work location. In the work area, you will need to make the utility. Just type: # make -f Makefile.sub afmtodit You may also need to copy /usr/contrib/groff/devps/generate/textmap to /usr/share/groff_font/devps/generate if it does not already exist. Once all these utilities are in place, you are ready to commence: Create the .afm file by typing: % gs -dNODISPLAY -q -- ttf2pf.ps TTF_name PS_font_name AFM_name Where, TTF_name is your TrueType font file, PS_font_name is the file name for the .pfa file, AFM_name is the name you wish for the .afm file. If you do not specify output file names for the .pfa or .afm files, then default names will be generated from the TrueType font file name. This also produces a .pfa file, the ascii PostScript font metrics file (.pfb is for the binary form). This will not be needed, but could (I think) be useful for a fontserver. For example, to convert the 30f9 Barcode font using the default file names, use the following command: % gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf Aladdin Ghostscript 5.10 (1997-11-23) Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved. This software comes with NO WARRANTY: see the file PUBLIC for details. Converting 3of9.ttf to 3of9.pfa and 3of9.afm. If you want the converted fonts to be stored in A.pfa and B.afm, then use this command: % gs -dNODISPLAY -- ttf2pf.ps 3of9.ttf A B Aladdin Ghostscript 5.10 (1997-11-23) Copyright (C) 1997 Aladdin Enterprises, Menlo Park, CA. All rights reserved. This software comes with NO WARRANTY: see the file PUBLIC for details. Converting 3of9.ttf to A.pfa and B.afm. Create the groff PostScript file: Change directories to /usr/share/groff_font/devps so as to make the following command easier to execute. You will probably need root privileges for this. (Or, if you are paranoid about working there, make sure you reference the files DESC, text.enc and generate/textmap as being in this directory.) % afmtodit -d DESC -e text.enc file.afm \ generate/textmap PS_font_name Where, file.afm is the AFM_name created by ttf2pf.ps above, and PS_font_name is the font name used from that command, as well as the name that &man.groff.1; will use for references to this font. For example, assuming you used the first tiff2pf.ps command above, then the 3of9 Barcode font can be created using the command: % afmtodit -d DESC -e text.enc 3of9.afm \ generate/textmap 3of9 Ensure that the resulting PS_font_name file (e.g., 3of9 in the example above) is located in the directory /usr/share/groff_font/devps by copying or moving it there. Note that if ttf2pf.ps assigns a font name using the one it finds in the TrueType font file and you want to use a different name, you must edit the .afm file prior to running afmtodit. This name must also match the one used in the Fontmap file if you wish to pipe &man.groff.1; into &man.gs.1;. Can TrueType fonts be used with other programs? The TrueType font format is used by Windows, Windows 95, and Mac's. It is quite popular and there are a great number of fonts available in this format. Unfortunately, there are few applications that I am aware of that can use this format: Ghostscript and Povray come to mind. Ghostscript's support, according to the documentation, is rudimentary and the results are likely to be inferior to type 1 fonts. Povray version 3 also has the ability to use TrueType fonts, but I rather doubt many people will be creating documents as a series of raytraced pages :-). This rather dismal situation may soon change. The FreeType Project is currently developing a useful set of FreeType tools: The freetype module is included with XFree86 4.x. For more information please see the FreeBSD Handbook or the XFree86 4.0.2 Fonts page. The xfsft font server for X11 can serve TrueType fonts in addition to regular fonts. Though currently in beta, it is said to be quite usable. See Juliusz Chroboczek's page for further information. Porting instructions for FreeBSD can be found at Stephen Montgomery's software page. xfstt is another font server for X11, available under . A program called ttf2bdf can produce BDF files suitable for use in an X environment from TrueType files. Linux binaries are said to be available from . For people requiring the use of Asian TrueType fonts, the XTT font server may be worth a look. Information about XTT can be found at URL: . and others … The FreeType Projects page is a good starting point for information on these and other free TrueType projects. Where can additional fonts be obtained? Many fonts are available on the Internet. They are either entirely free, or are share-ware. In addition, there are many inexpensive CDROMs available that contain many fonts. Some Internet locations (as of August 1996) are: (Formerly CICA) Additional questions What use are the .pfm files? Can one generate the .afm file from a .pfa or .pfb? How to generate the groff character mapping files for PostScript fonts with non-standard character names? - Can xditview and devX?? devices be setup to access all + Can xditview and devX?? devices be set up to access all the new fonts? It would be good to have examples of using TrueType fonts with povray and ghostscript.
diff --git a/en_US.ISO8859-1/articles/hubs/article.sgml b/en_US.ISO8859-1/articles/hubs/article.sgml index 4d328c805c..10ff657e91 100644 --- a/en_US.ISO8859-1/articles/hubs/article.sgml +++ b/en_US.ISO8859-1/articles/hubs/article.sgml @@ -1,1133 +1,1133 @@ %man; %authors; %teams; %mailing-lists; %trademarks; ]>
Mirroring FreeBSD $FreeBSD$ Jun Kuriyama
kuriyama@FreeBSD.org
 Valentino Vaschetto
logo@FreeBSD.org
 Daniel Lang
dl@leo.org
 Ken Smith
kensmith@cse.buffalo.edu
 &tm-attrib.freebsd; &tm-attrib.general; An in-progress article on how to mirror FreeBSD, aimed at hub administrators. Contact Information The Mirror System Coordinators can be reached through email at mirror-admin@FreeBSD.org. There is also a &a.hubs;. Requirements for FreeBSD mirrors Disk Space Disk space is one of the most important requirements. Depending on the set of releases, architectures, and degree of completeness you want to mirror, a huge amount of disk space may be consumed. Also keep in mind that official mirrors are probably required to be complete. The CVS repository and the web pages should always be mirrored completely. Also note that the numbers stated here are reflecting the current state (at 4.9-RELEASE/5.1-RELEASE). Further development and releases will only increase the required amount. Also make sure to keep some (ca. 10-20%) extra space around just to be sure. Here are some approximate figures: Full FTP Distribution: 126 GB CVS repository: 2.7 GB CTM deltas: 1.8 GB Webpages: 300 MB Network Connection/Bandwidth Of course, you need to be connected to the Internet. The required bandwidth depends on your intended use of the mirror. If you just want to mirror some parts of FreeBSD for local use at your site/intranet, the demand may be much smaller than if you want to make the files publicly available. If you intend to become an official mirror, the bandwidth required will be even higher. We can only give rough estimates here: Local site, no public access: basically no minimum, but < 2 Mbps could make syncing too slow. Unofficial public site: 34 Mbps is probably a good start. Official site: > 100 Mbps is recommended, and your host should be connected as close as possible to your border router. System Requirements, CPU, RAM One thing this depends on the expected number of clients, which is determined by the server's policy. It is also affected by the types of services you want to offer. Plain FTP or HTTP services may not require a huge amount of resources. Watch out if you provide CVSup, rsync or even AnonCVS. This can have a huge impact on CPU and memory requirements. Especially rsync is considered a memory hog, and CVSup does indeed consume some CPU. For AnonCVS it might be a nice idea to set up a memory resident file system (MFS) of at least 300 MB, so you need to take this into account for your memory requirements. The following are just examples to give you a very rough hint. For a moderately visited site that offers rsync, you might consider a current CPU with around 800MHz - 1 GHz, and at least 512MB RAM. This is probably the minimum you want for an official site. For a frequently used site you definitely need more RAM (consider 2GB as a good start) and possibly more CPU, which could also mean that you need to go for a SMP system. You also want to consider a fast disk subsystem. Operations on the CVS repository require a fast disk subsystem (RAID is highly advised). A SCSI controller that has a cache of its own can also speed up things since most of these services incur a large number of small modifications to the disk. Services to offer Every mirror site is required to have a set of core services available. In addition to these required services, there are a number of optional services that server administrators may choose to offer. This section explains which services you can provide and how to go about implementing them. FTP (required for FTP fileset) This is one of the most basic services, and it is required for each mirror offering public FTP distributions. FTP access must be anonymous, and no upload/download ratios are allowed (a ridiculous thing anyway). Upload capability is not required (and must never be allowed for the FreeBSD file space). Also the FreeBSD archive should be available under the path /pub/FreeBSD. There is a lot of software available which can be set up to allow anonymous FTP (in alphabetical order). /usr/libexec/ftpd: FreeBSD's own ftpd can be used. Be sure to read &man.ftpd.8;. ftp/ncftpd: A commercial package, free for educational use. ftp/oftpd: An ftpd designed with security as a main focus. ftp/proftpd: A modular and very flexible ftpd. ftp/pure-ftpd: Another ftpd developed with security in mind. ftp/twoftpd: As above. ftp/vsftpd: The very secure ftpd. ftp/wu-ftpd: The ftpd from Washington University. It has become infamous, because of the huge amount of security issues that have been found in it. If you do choose to use this software be sure to keep it up to date. FreeBSD's ftpd, proftpd, wu-ftpd and maybe ncftpd are among the most commonly ones. The others do not have a large userbase among mirror sites. One thing to consider is that you may need flexibility in limiting how many simultaneous connections are allowed, thus limiting how much network bandwidth and system resources are consumed. RSYNC (optional for FTP fileset) rsync is often offered for access to the contents of the FTP area of FreeBSD, so other mirror sites can use your system as their source. The protocol is different from FTP in many ways. It is much more bandwidth friendly, as only differences between files are transferred instead of whole files when they change. rsync does require a significant amount of memory for each instance. The size depends on the size of the synced module in terms of the number of directories and files. rsync can use rsh and ssh (now default) as a transport, or use it's own protocol for stand-alone access (this is the preferred method for public rsync servers). Authentication, connection limits, and other restrictions may be applied. There is just one software package available: net/rsync HTTP (required for webpages, optional for FTP fileset) If you want to offer the FreeBSD webpages, you need to install a webserver a.k.a. httpd. You may optionally offer the FTP fileset via HTTP. The choice of Webserver software is left up to the mirror administrator. Some of the most popular choices are: www/apache13: Apache is the most widely deployed Webserver on the Internet. It is used extensively by the FreeBSD Project. You may also wish to use the next generation of the Apache Webserver, available in the ports collection as www/apache2. www/thttpd: If you are going to be serving a large amount of static content you may find that using an application such as tHttpd is more efficient than Apache. It is optimized for excellent performance on FreeBSD. www/boa: Boa is another alternative to tHttpd and Apache. It should provide considerably better performance than Apache for purely static content. It does not, at the time of writing, contain the same set of optimizations for FreeBSD that are found in tHttpd. CVSup (desired for CVS repository) CVSup is a very efficient way of distributing files. It works similar to rsync, but was specially designed for use with CVS repositories. If you want to offer the FreeBSD CVS repository, you really want to consider offering it via CVSup. It is possible to offer the CVS repository via AnonCVS, FTP, Rsync or HTTP, but people would benefit much more from CVSup access. CVSup was developed by &a.jdp;. It is a bit tricky to install on non-FreeBSD platforms, since it is written in Modula-3 and therefore requires a Modula-3 environment. John Polstra has built a stripped down version of M3 that is sufficient to run CVSup, and can be installed much easier. See Ezm3 for details. Related ports are: net/cvsup: The native CVSup port (client and server) which requires lang/ezm3 now. net/cvsup-mirror: The CVSup mirror kit, which requires net/cvsup, and configures it mirror-ready. Some site administrators may want a different setup though. There are a few more like net/cvsupit and net/cvsup-without-gui you might want to have a look at. If you prefer a static binary package, take a look here. This page still refers to the S1G bug that was present in CVSup. Maybe - John will setup a generic download-site to get + John will set up a generic download-site to get static binaries for various platforms. It is possible to use CVSup to offer any kind of fileset, not just CVS repositories, but configuration can be complex. CVSup is known to eat some CPU on both the server and the client, since it needs to compare lots of files. AnonCVS (optional for CVS repository) If you have the CVS repository, you may want to offer anonymous CVS access. A short warning first: There is not much demand for it, it requires some experience, and you need to know what you are doing. Generally there are two ways to access a CVS repository remotely: via pserver or via ssh (we don't consider rsh). For anonymous access, pserver is very well suited, but some still offer ssh access as well. There is a custom crafted wrapper in the CVS repository, to be used as a login-shell for the anonymous ssh account. It does a chroot, and therefore requires the CVS repository to be available under the anonymous user's home-directory. This may not be possible for all sites. If you just offer pserver this restriction does not apply, but you may run with more security risks. You don't need to install any special software, since &man.cvs.1; comes with FreeBSD. You need to enable access via inetd, so add an entry into your /etc/inetd.conf like this: cvspserver stream tcp nowait root /usr/bin/cvs cvs -f -l -R -T /anoncvstmp --allow-root=/home/ncvs pserver See the manpage for details of the options. Also see the CVS info page about additional ways to make sure access is read-only. It is advised that you create an unprivileged account, preferably called anoncvs. Also you need to create a file passwd in your /home/ncvs/CVSROOT and assign a CVS password (empty or anoncvs) to that user. The directory /anoncvstmp is a special purpose memory based file system. It is not required but advised since &man.cvs.1; creates a shadow directory structure in your /tmp which is not used after the operation but slows things dramatically if real disk operations are required. Here is an excerpt from /etc/fstab, how to set up such a MFS: /dev/da0s1b /anoncvstmp mfs rw,-s=786432,-b=4096,-f=512,-i=560,-c=3,-m=0,nosuid,nodev 0 0 This is (of course) tuned a lot, and was suggested by &a.jdp;. How to Mirror FreeBSD Ok, now you know the requirements and how to offer the services, but not how to get it. :-) This section explains how to actually mirror the various parts of FreeBSD, what tools to use, and where to mirror from. FTP The FTP area is the largest amount of data that needs to be mirrored. It includes the distribution sets required for network installation, the branches which are actually snapshots of checked-out source trees, the ISO Images to write CD-ROMs with the installation distribution, a live file system, lots of packages, the ports tree, distfiles, and a huge amount of packages. All of course for various FreeBSD versions, and various architectures. With FTP mirror You can use a FTP mirror program to get the files. There are a lot around and widely used, like: ftp/mirror ftp/ftpmirror ftp/emirror ftp/spegla ftp/omi some even use ftp/wget ftp/mirror was very popular, but seemed to have some drawbacks, as it is written in &man.perl.1;, and had real problems with mirroring large directories like a FreeBSD site. There are rumors that the current version has fixed this by allowing a different algorithm for comparing the directory structure to be specified. In general FTP is not really good for mirroring. It transfers the whole file if it has changed, and does not create a single data stream which would benefit from a large TCP congestion window. With RSYNC A better way to mirror the FTP area is rsync. You can install the port net/rsync and then use rsync to sync with your upstream host. rsync is already mentioned in . Since rsync access is not required, your preferred upstream site may not allow it. You may need to hunt around a little bit to find a site that allows rsync access. Since the number of rsync clients will have a significant impact on the server machine, most admins impose limitations on their server. For a mirror, you should ask the site maintainer you are syncing from about their policy, and maybe an exception for your host (since you are a mirror). A command line to mirror FreeBSD could look like that: &prompt.user; rsync -vaz --delete ftp4.de.FreeBSD.org::FreeBSD/ /pub/FreeBSD/ Consult the documentation for rsync, which is also available at http://rsync.samba.org/ about the various options to be used with rsync. If you sync the whole module (unlike subdirectories), be aware that the module-directory (here "FreeBSD") will not be created, so you cannot omit the target directory. Also you might want to set up a script framework that calls such a command via &man.cron.8;. With CVSup A few sites, including the one-and-only ftp-master.FreeBSD.org even offer CVSup to mirror the contents of the FTP space. You need to install a cvsup client, preferably from the port net/cvsup. (Also reread .) A sample supfile suitable for ftp-master.FreeBSD.org looks like this: # # FreeBSD archive supfile from master server # *default host=ftp-master.FreeBSD.org *default base=/usr *default prefix=/pub #*default release=all *default delete use-rel-suffix *default umask=002 # If your network link is a T1 or faster, comment out the following line. #*default compress FreeBSD-archive release=all preserve It seems CVSup would be the best way to mirror the archive in terms of efficiency, but it is only available from few sites. Please have look at the CVSup documentation like &man.cvsup.1; and consider using the option, as it can reduce the amount of work to be done a lot. Mirroring the CVS repository Again you have various possibilities, but the most recommended one is to use CVSup. Using CVSup CVSup was already described to some detail in and . Here we just describe an example to set up the supfile: # # FreeBSD CVS supfile from master server # *default host=cvsup-master.FreeBSD.org *default base=/usr *default prefix=/pub/FreeBSD/development/FreeBSD-CVS *default release=cvs *default delete use-rel-suffix *default umask=002 # If your network link is a T1 or faster, comment out the following line. #*default compress cvs-all You should also have a look at /usr/share/examples/cvsup Please do not forget to consider the hint mentioned in this note above. Using other methods Using other methods than CVSup is generally not recommended. We describe them in short here anyway. Since most sites offer the CVS repository as part of the FTP fileset under the path /pub/FreeBSD/development/FreeBSD-CVS, the following methods could be used. FTP RSYNC maybe even HTTP If you find a site that supports it, you could use net/sup. But it is inferior to CVSup and its deficiencies caused John Polstra to develop CVSup in the first place, so it is clearly not recommended. You can NOT use AnonCVS to mirror the CVS repository since CVS does not allow you to access the repository itself, but only checked out versions of the modules. Mirroring the WWW pages The best way is to check out the www distribution from CVS. If you have a local mirror of the CVS repository, it is probably as easy as: &prompt.user; cvs -d /home/ncvs co www and a cronjob, that calls cvs up -d -P on a regular basis, maybe just after your repository was updated. Of course, the files need to remain in a directory available for public WWW access. The installation and configuration of a webserver is not discussed here. For the website to be visible, users must execute the &man.make.1; command in the main www directory. This command will create the standard *.html files for web viewing. For this to work however, the textproc/docproj port must be installed. If you don't have a local repository, you can use CVSup to maintain an up to date copy of the www pages. A sample supfile can be found in /usr/share/examples/cvsup/www-supfile and could look like this: # # WWW module supfile for FreeBSD # *default host=cvsup3.de.FreeBSD.org *default base=/usr *default prefix=/usr/local *default release=cvs tag=. *default delete use-rel-suffix # If your network link is a T1 or faster, comment out the following line. *default compress # This collection retrieves the www/ tree of the FreeBSD repository www Using ftp/wget or other web-mirror tools is probably not recommended. Mirroring the FreeBSD documentation Since the documentation is referenced a lot from the webpages, it is recommended that you mirror the FreeBSD documentation as well. However, this is not as trivial as the www-pages alone. First of all, you should get the doc sources, again preferably via CVSup. Here is a corresponding sample supfile: # # FreeBSD documentation supfile # *default host=cvsup3.de.FreeBSD.org *default base=/usr *default prefix=/usr/share *default release=cvs tag=. *default delete use-rel-suffix # If your network link is a T1 or faster, comment out the following line. #*default compress # This will retrieve the entire doc branch of the FreeBSD repository. # This includes the handbook, FAQ, and translations thereof. doc-all Then you need to install a couple of ports. You are lucky, there is a meta-port: textproc/docproj to do the work for you. You need to set up some environment variables, like SGML_CATALOG_FILES. Also have a look at your /etc/make.conf (copy /etc/defaults/make.conf if you do not have one), and look at the DOC_LANG variable. Now you are probably ready to run make in you doc directory (/usr/share/doc by default) and build the documentation. Again you need to make it accessible for your webserver and make sure the links point to the right location. The building of the documentation, as well as lots of side issues, is documented itself in: fdp-primer. Please read this piece of documentation, especially if you have problems building the documentation. XXX MAYBE THIS CAN BE LINKED FROM WITHIN - NOT USING AN ABSOLUTE URL XXX How often should I mirror? Every mirror should be updated on a regular basis. You will certainly need some script framework for it that will be called by &man.cron.8;. Since nearly every admin does this his own way, we cannot give specific instructions. It could work like this: Put the command to run your mirroring application in a script. Use of a plain /bin/sh script is recommended. Add some output redirections so diagnostic messages are logged to a file. Test if your script works. Check the logs. Use &man.crontab.1; to add the script to the appropriate user's &man.crontab.5;. This should be a different user than what your FTP daemon runs as so that if file permissions inside your FTP area are not world-readable those files can not be accessed by anonymous FTP. This is used to stage releases — making sure all of the official mirror sites have all of the necessary release files on release day. Here are some recommended schedules: FTP fileset: daily CVS repository: daily to hourly WWW pages: daily Where to mirror from This is an important issue. So this section will spend some effort to explain the backgrounds. We will say this several times: under no circumstances should you mirror from ftp.FreeBSD.org. A few words about the organization Mirrors are organized by country. All official mirrors have a DNS entry of the form ftpN.CC.FreeBSD.org. CC (i.e. country code) is the top level domain (TLD) of the country where this mirror is located. N is a number, telling that the host would be the Nth mirror in that country. (Same applies to cvsupN.CC.FreeBSD.org, wwwN.CC.FreeBSD.org, etc.) There are mirrors with no CC part. These are the mirror sites that are very well connected and allow a large number of concurrent users. ftp.FreeBSD.org is actually two machines, one currently located in Denmark and the other in the United States. It is NOT a master site and should never be used to mirror from. Lots of online documentation leads interactiveusers to ftp.FreeBSD.org so automated mirroring systems should find a different machine to mirror from. Additionally there exists a hierarchy of mirrors, which is described in terms of tiers. The master sites are not referred to but can be described as Tier-0. Mirrors that mirror from these sites can be considered Tier-1, mirrors of Tier-1-mirrors, are Tier-2, etc. Official sites are encouraged to be of a low tier, but the lower the tier the higher the requirements in terms as described in . Also access to low-tier-mirrors may be restricted, and access to master sites is definitely restricted. The tier-hierarchy is not reflected by DNS and generally not documented anywhere except for the master sites. However, official mirrors with low numbers like 1-4, are usually Tier-1 (this is just a rough hint, and there is no rule). Ok, but where should I get the stuff now? Under no circumstances should you mirror from ftp.FreeBSD.org. The short answer is: from the site that is closest to you in Internet terms, or gives you the fastest access. I just want to mirror from somewhere! If you have no special intentions or requirements, the statement in applies. This means: Look at available mirrors in your country. The FreeBSD Mirror Database can help you with this. Check for those which provide fastest access (number of hops, round-trip-times) and offer the services you intend to use (like rsync or CVSup). Contact the administrators of your chosen site stating your request, and asking about their terms and policies. - Setup your mirror as described above. + Set up your mirror as described above. I'm an official mirror, what is the right site for me? In general the description in still applies. Of course you may want to put some weight on the fact that your upstream should be of a low tier. There are some other considerations about official mirrors that are described in . I want to access the master sites! If you have good reasons and good prerequisites, you may want and get access to one of the master sites. Access to these sites is generally restricted, and there are special policies for access. If you are already an official mirror, this certainly helps you getting access. In any other case make sure your country really needs another mirror. If it already has three or more, ask the zone administrator (hostmaster@CC.freebsd.org) or &a.hubs; first. Whoever helped you become, an official should have helped you gain access to an appropriate upstream host, either one of the master sites or a suitable Tier-1 site. If not, you can send email to mirror-admin@FreeBSD.org to request help with that. There are three master sites for the FTP fileset and one for the CVS repository (the webpages and docs are obtained from CVS, so there is no need for master). ftp-master.FreeBSD.org This is the master site for the FTP fileset. ftp-master.FreeBSD.org provides rsync and CVSup access, rather in addition to ftp protocol. Refer to and how to access via these protocols. Mirrors should be encouraged to also allow rsync access for the FTP contents, since they are Tier-1-mirrors. cvsup-master.FreeBSD.org This is the master site for the CVS repository. cvsup-master.FreeBSD.org provides CVSup access only. See for details. To get access, you need to contact &a.cvsup-master;. Make sure you read FreeBSD CVSup Access Policy first! Set up the required authentication by following these instructions. Make sure you specify the server as freefall.FreeBSD.org on the cvpasswd command line, as described in this document, even when you are contacting cvsup-master.FreeBSD.org Official Mirrors Official mirrors are mirrors that a) have a FreeBSD.org DNS entry (usually a CNAME). b) are listed as an official mirror in the FreeBSD documentation (like handbook). So far to distinguish official mirrors. Official mirrors are not necessarily Tier-1-mirrors. However you probably won't find a Tier-1-mirror, that is not also official. Special Requirements for official (tier-1) mirrors It is not so easy to state requirements for all official mirrors, since the project is sort of tolerant here. It is more easy to say, what official tier-1 mirrors are required to. All other official mirrors can consider this a big should. The following applies mainly to the FTP fileset, since a CVS repository should always be mirrored completely, and the webpages are a case of its own. Tier-1 mirrors are required to: carry the complete fileset allow access to other mirror sites provide FTP and RSYNC access Furthermore, admins should be subscribed to the &a.hubs;. See this link for details, how to subscribe. It is very important for a hub administrator, especially Tier-1 hub admins, to check the release schedule for the next FreeBSD release. This is important because it will tell you when the next release is scheduled to come out, and thus giving you time to prepare for the big spike of traffic which follows it. It is also important that hub administrators try to keep their mirrors as up-to-date as possible (again, even more crucial for Tier-1 mirrors). If Mirror1 doesn't update for a while, lower tier mirrors will begin to mirror old data from Mirror1 and thus begins a downward spiral... Keep your mirrors up to date! How to become official then? An interesting question, especially, since the state of being official comes with some benefits, like a much higher bill from your ISP as more people will be using your site. Also it may be a key requirement to get access to a master site. Before applying, please consider (again) if another official mirror is really needed for your region. Check first with your zone administrator (hostmaster@CC.FreeBSD.org) or, if that fails, ask on the &a.hubs;. Ok, here is how to do it: Get the mirror running in first place (maybe not using a master site, yet). Subscribe to the &a.hubs;. If everything works so far, contact the DNS administrator responsible for your region/country, and ask for a DNS entry for your site. The admin should able to be contacted via hostmaster@CC.FreeBSD.org, where CC is your country code/TLD. Your DNS entry will be as described in . If there is no subdomain set up for your country yet, you should contact mirror-admin@FreeBSD.org, or you can try the &a.hubs; first. Whoever helps you get an official name should send email to mirror-admin@FreeBSD.org so your site will be added to the mirror list in the FreeBSD Handbook. That is it. Some statistics from mirror sites Here are links to the stat pages of your favorite mirrors (a.k.a. the only ones who feel like providing stats). FTP site statistics ftp2.FreeBSD.org - grisha@ispol.com - (Bandwidth) ftp.is.FreeBSD.org - hostmaster@is.FreeBSD.org - (Bandwidth) (FTP processes) (HTTP processes) ftp.cz.FreeBSD.org - cejkar@fit.vutbr.cz - (Bandwidth) (FTP processes) (Rsync processes) ftp4.de.FreeBSD.org - dl@leo.org - (FTP users) (RSYNC users) CVSup site stats cvsup5.FreeBSD.org - staff@blackened.com - (CVSup processes) cvsup[23456].jp.FreeBSD.org - kuriyama@FreeBSD.org - (CVSup processes) cvsup.cz.FreeBSD.org - cejkar@fit.vutbr.cz - (CVSup processes) [cvsup3|anoncvs].de.FreeBSD.org - dl@leo.org - (CVSup processes)
diff --git a/en_US.ISO8859-1/articles/java-tomcat/article.sgml b/en_US.ISO8859-1/articles/java-tomcat/article.sgml index c6e57bfcfe..fcb4ba2488 100644 --- a/en_US.ISO8859-1/articles/java-tomcat/article.sgml +++ b/en_US.ISO8859-1/articles/java-tomcat/article.sgml @@ -1,636 +1,636 @@ %trademarks; %man; ]>
&java; and Jakarta Tomcat on FreeBSD Victoria Chan
vkchan@kendryl.net
 Hiten Pandya
hiten@uk.FreeBSD.org
 2002 Victoria Chan Hiten Pandya $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.linux; &tm-attrib.microsoft; &tm-attrib.sun; &tm-attrib.general; This document is presented in hopes of making it easier for anyone that needs to get &java; up and running on FreeBSD, with the least amount of aggravation. Plan on spending a whole day on such a project as it will take time to assemble all the pieces and compile them individually, and then as a whole. It also shows how to install the famous Jakarta Tomcat Servlet and &jsp; container on the FreeBSD operating system. Introduction The &java; programming language was birthed on May 23rd 1995. One would expect that after all this time, &java; applications would be easy to install and ready to run from a single package, or port on FreeBSD, thus making it available for the masses. This is not the case, unfortunately, as the &java; distribution is held very closely by Sun Microsystems, and prohibits re-distribution. All &java; Applets must be compiled from source code, together with the &java; Development Kit from Sun Microsystems. All these ingredients must be blended together in the right order, assembled, and compiled by the end user. With such distribution philosophies at heart, it is my opinion that &java; will always be developer or hacker use only. I certainly found this to be true when I needed to serve up some .jsp pages for a client on my web server, and needed to get www/jakarta-tomcat to work with www/apache13 on my FreeBSD system. The Tomcat portion of the install is very straight forward, but the difficulty I had was getting &java; Development Kit up and running for FreeBSD 4.X, as Sun Microsystems only supplies Binaries for Linux, &solaris;, and &windowsnt;. This means that I had to compile my own &jdk; for FreeBSD. I began by searching for documentation on the Internet. I quickly found that there is more source code than I need along with patches to the source code, but very little documentation of what to do after obtaining everything. In this article, you will find how to install the &java; Development Kit for FreeBSD, and how to get up and running with Tomcat. A section is also provided for further reading. The &java; Environment Ensure that you have the current ports collection as make it will fail if it attempts to build older source. You can upgrade your entire ports collection by using CVSup. See for more information. You can also download the ports you need manually from to get you going. You will need the Linux Emulation (Linux-ABI) enabled in your kernel configuration. Simply add the following option to your kernel configuration file and recompile it. Instructions for building a kernel can be found in the FreeBSD Handbook. options COMPAT_LINUX The above option will add Linux-ABI support to your kernel, when it is recompiled. The list of dependencies below, are required to be installed manually in a certain order. Dependencies that are automatically downloaded are not listed here. java/jdk13 java/linux-jdk13 archivers/gtar archivers/bzip2 archivers/unzip archivers/zip You will need to get the following: Download bsd-jdk131-patches-5.tar.gz from and place it under /usr/ports/distfiles. Next get out your web browser and head on over to and find SDK downloads. Click on the continue button below GNUZIP Tar Shell Script. Be sure you read every word of the license page before you click on the Accept button! You will be brought to a page titled Download Java(TM) 2 SDK, Standard Edition 1.3.1_02. Scroll to the bottom and click on the HTTP download button. When the File Download box comes up, be sure to click on the Open button rather than the Save button. You will be presented with another File Download box - this time choose Save and you will be able to save j2sdk-1_3_1_02-linux-i386.bin. Place it in /usr/ports/distfiles. Go to . In the table under Produce Description, named Java 2 SDK 1.3.1, go to the right-hand cell and click download. You will be taken to the Sign On page, where you must sign in if you already have an account, or register for access. Once you have signed on, you will be taken to the Legal page, where you must accept the license agreement; scroll down (reading the license) and click on the Continue button. Next page, is the Receipt page. This is where you will save your order number. You will be able to choose the location that is nearest to you. Click on Java 2 SDK, Standard Edition, version 1.3.1. Save the j2sdk-1_3_1-src.tar.gz to the /usr/ports/distfiles/ directory. It is very important for you to read the License Agreement which has been issued by Sun Microsystems Corp. There are several restrictions in place on the use of &java;, which you must address. The FreeBSD Project does not take any responsibilities for your actions. Do not discard any of the downloaded files, as they will be needed for building some of the native ports for FreeBSD, which are discussed later on. Now that you have assembled all the source files and ports, you need to start by building java/linux-jdk13: &prompt.root; cd /usr/ports/archivers/gtar; make all install clean &prompt.root; cd /usr/ports/archivers/unzip; make all install clean &prompt.root; cd /usr/ports/archivers/zip; make all install clean And finally: &prompt.root; cd /usr/ports/java/linux-jdk13 &prompt.root; make all install clean Once you have built java/linux-jdk13, you need to test it, to make sure it works as intended. To do that: &prompt.root; cd /usr/local/linux-jdk1.3.1/bin &prompt.root; ./java -version The output of the above command should be as follows: java version "1.3.1_02" Java(TM) 2 Runtime Environment, Standard Edition (build 1.3.1_02-b02) Classic VM (build 1.3.1_02-b02, green threads, nojit) If you did not get the correct response, you need to: &prompt.root; cd /usr/ports/java/linux-jdk13 &prompt.root; make deinstall And make sure that /usr/local does not contain a linux-jdk1.3.1 directory. If you find a fragment of the directory, delete it. Repeat the build and install process for java/linux-jdk13. To make the native Java Development Kit 1.3.1 for FreeBSD, do the following: Make sure you have the j2sdk-1_3_1-src.tar.gz file in your /usr/ports/distfiles. This file is needed for applying the patch-sets discussed below. You will need to download the patch set for building the port. The patch-set file is called bsd-jdk131-patches-6.tar.gz. You should also make sure the integrity of the files by matching it with the following MD5 checksum. MD5 (bsd-jdk131-patches-6.tar.gz) = 9cade10b81d6034fdd2176bef32bdbf9 The patch-set is available from: The last procedure discussed above (building the native &jdk;) will take some time. Jakarta Tomcat Setup Overview &java; is becoming an even more popular for making diverse and scalable platform independent solutions. One of the most growing needs of &java; is in the ASP (Application Service Provider) market. &java; serves as the perfect solution for these types of markets, with the following advantages: Platform Independence Industry Wide Commitment Scalability Reliable Performance Distributed, Multi-threaded, Secure etc. A very important and growing technology which has emerged from &java; is &jsp; (&javaserver.pages;). &jsp; (&javaserver.pages;) is a server-side technology introduced by Sun Microsystems Corp., which provides a quick simple way to generate dynamic content from within HTML pages. It uses XML tags along with &java; scriptlets to encapsulate and separate the logic from the design and display. When a &jsp; page is invoked, it is dynamically converted into a Servlet and processed by the server to produce the resulting HTML/XML page for the client. When &jsp; is used in conjunction with JavaBeans, it is possible to produce very diverse and scalable applications, which may be combined with the strength and performance of FreeBSD. Tomcat is an open-source implementation of the &java; Servlets and &javaserver.pages; technologies, developed under the Jakarta project at the Apache Software Foundation. Tomcat implements a new Servlet framework (called Catalina) that is based on completely new architecture with the Servlet 2.3 and &jsp; 1.2 specifications. It includes many additional features that make it a useful platform for developing and deploying web applications and web services. In a nutshell, Tomcat is an application server written in 100% Pure &java;. Tomcat is used for many purposes, and is not limited to Application Servers. It provides an open platform to develop extensible web and content management services. When Tomcat is used with an optimized FreeBSD system, it can provide highly reliable and fast pacing services. Please refer to the section for more information on Tomcat and &jsp;. The next section will demonstrate how to build the Tomcat Environment for FreeBSD. The version of Tomcat used in this guide is 4.0.3. This version contains major bug fixes, and the following updates/changes: JSP 1.2 Specification Java Servlet 2.3 Specification Full backward compatibility with the Java Servlet 2.2 and JSP 1.1 Specification The Tomcat environment for FreeBSD It is very simple to install Tomcat on a FreeBSD machine, after setting up the necessary &java; environment, which we have previously completed. - In-order to setup Tomcat on FreeBSD, follow the below + In-order to set up Tomcat on FreeBSD, follow the below procedure: - Follow the above steps to setup the necessary &java; + Follow the above steps to set up the necessary &java; environment. Set an environment variable JAVA_HOME which, points to the directory where you have installed the &jdk; (the examples below point to a native build of the &jdk;). If you are using &man.sh.1; as your shell, you can set JAVA_HOME with: &prompt.root; export JAVA_HOME="/usr/local/jdk1.3.1" Those who use &man.csh.1; or a compatible shell, must use a slightly different command: &prompt.root; setenv JAVA_HOME /usr/local/jdk1.3.1 This environment variable should be made permanent by adding it into either .profile or .cshrc, depending on the shell you are using. This variable is very crucial for the functioning of all the &java; based programs, including Tomcat itself. Download the Tomcat binary distribution from the Jakarta website, which is located at . The file to download is called jakarta-tomcat-4.0.3.tar.gz. The compressed and archived file we downloaded in the previous step uses special GNU Extensions. In-order to untar and uncompress the file, we will need to install GNU Tar (archivers/gtar), by doing the following: &prompt.root; cd /usr/ports/archivers/gtar && make all install clean Un-tar and Un-compress the jakarta-tomcat-4.0.3.tar.gz file into the /usr/local directory and rename the directory to tomcat-4.0 for ease of reference: &prompt.root; cd /usr/local &prompt.root; gtar zxvf jakarta-tomcat-4.0.3.tar.gz &prompt.root; ls jakarta* jakarta-tomcat-4.0.3 &prompt.root; mv jakarta-tomcat-4.0.3 tomcat-4.0 You can remove the jakarta-tomcat-4.0.3.tar.gz at your preference. Installation by using the source code is currently out of scope for this document. Please refer to the following files for addition information on building from source, available from your Tomcat distribution directory: /usr/local/tomcat-4.0/README.txt /usr/local/tomcat-4.0/BUILDING.txt Operating Tomcat - Basics Now that we have finished installing Tomcat. The following example shows how to start the Tomcat server: &prompt.root; cd /usr/local/tomcat-4.0/bin &prompt.root; ./startup.sh (for starting Tomcat) You can test if your Tomcat server has started by visiting the following URL: http://127.0.0.1:8080 or http://localhost:8080. To stop Tomcat: &prompt.root; cd /usr/local/tomcat-4.0/bin &prompt.root; ./shutdown.sh (for stopping Tomcat) The startup.sh and shutdown.sh are frontends to the catalina.sh executable script in the same directory; if you would like to start Tomcat automatically at boot-time run: &prompt.root; cd /usr/local/etc/rc.d &prompt.root; ln -s /usr/local/tomcat-4.0/bin/catalina.sh Edit the catalina.sh, and add the following at the beginning of the file (after the comment box): JAVA_HOME=/usr/local/jdk1.3.1 If your port 8080 is occupied by some other service, you can change it by editing the server.xml in your Tomcat's conf/ directory. In the example below, the port will be changed to 80, assuming there is no service running on that port. &prompt.root; cd /usr/local/tomcat-4.0/conf &prompt.root; fgrep -n 8080 server.xml ~65: By default, a non-SSL HTTP/1.1 Connector is established on port 8080. ~89: port="8080" minProcessors="5" maxProcessors="75" &prompt.root; cat server.xml | sed s/8080/80/ > server.xml.new &prompt.root; mv server.xml.new server.xml Reference The FreeBSD &java; Project JavaSoft. Home of &java; The Sun Community Source Licensing for &java; Jakarta Tomcat Homepage J2SE Documentation FreeBSD Ports - &java; Section Conclusion Finally, we are at the end of the article and have a working version of Tomcat. We hope that you have learned the basics of installing and building the &java; Development Kit on FreeBSD, along with installation of the Tomcat binary distribution application server released by the Apache Software Foundation. The section contains pointers to additional resources on this topic, some which are in print, some which are on the World Wide Web, or both. The most important thing is drive space. I suggest having 700MB or more free space in /usr. I hope this article has helped you in some small way. For questions, comments, compliments, or rants, please direct them to Victoria Chan.
diff --git a/en_US.ISO8859-1/articles/mh/article.sgml b/en_US.ISO8859-1/articles/mh/article.sgml index 074c553e07..1bd1b1adba 100644 --- a/en_US.ISO8859-1/articles/mh/article.sgml +++ b/en_US.ISO8859-1/articles/mh/article.sgml @@ -1,819 +1,819 @@ %freebsd; %trademarks; ]>
An <application>MH</application> Primer Matt Midboe
matt@garply.com
v1.0, 16 January 1996 &tm-attrib.freebsd; &tm-attrib.opengroup; &tm-attrib.general; This document contains an introduction to using MH on FreeBSD Introduction MH started back in 1977 at the RAND Corporation, where the initial philosophies behind MH were developed. MH is not so much a monolithic email program but a philosophy about how best to develop tools for reading email. The MH developers have done a great job adhering to the KISS principle: Keep It Simple Stupid. Rather than have one large program for reading, sending and handling email they have written specialized programs for each part of your email life. One might liken MH to the specialization that one finds in insects and nature. Each tool in MH does one thing, and does it very well. Beyond just the various tools that one uses to handle their email MH has done an excellent job keeping the configuration of each of these tools consistent and uniform. In fact, if you are not quite sure how something is supposed to work or what the arguments for some command are supposed to be, then you can generally guess and be right. Each MH command is consistent about how it handles reading the configuration files and how it takes arguments on the command line. One useful thing to remember is that you can always add a to the command to have it display the options for that command. The first thing that you need to do is to make sure that you have installed the MH package on your FreeBSD machine. If you installed from CDROM you should be able to execute the following to load MH: &prompt.root; pkg_add /cdrom/packages/mh-6.8.3.tgz You will notice that it created a /usr/local/lib/mh directory for you as well as adding several binaries to the /usr/local/bin directory. If you would prefer to compile it yourself then you can anonymous ftp it from ftp.ics.uci.edu or louie.udel.edu. This primer is not a full comprehensive explanation of how MH works. This is just intended to get you started on the road to happier, faster mail reading. You should read the manual pages for the various commands. You might also want to read the comp.mail.mh newsgroup. Also you can read the FAQ for MH. The best resource for MH is Jerry Peek's MH & nmh: Email for Users & Programmers. Reading Mail This section covers how to use inc, show, scan, next, prev, rmm, rmf, and msgchk. One of the best things about MH is the consistent interface between programs. One thing to keep in mind when using these commands is how to specify message lists. In the case of inc this does not really make any sense but with commands like show it is useful to know. A message list can consist of something like 23 20 16 which will act on messages 23, 20 and 16. This is fairly simple but you can do more useful things like 23-30 which will act on all the messages between 23 and 30. You can also specify something like cur:10 which will act on the current message and the next 9 messages. The cur, last, and first messages are special messages that refer to the current, last or first message in the folder. <command>inc</command>, <command>msgchk</command>—read in your new email or check it If you just type in inc and hit return you will be well on your way to getting started with MH. The first - time you run inc it will setup your account + time you run inc it will set up your account to use all the MH defaults and ask you about creating a Mail directory under your HOME directory. If you have mail waiting to be downloaded you will see something that looks like: 29 01/15 Doug White Re: Another Failed to boot problem<<On Mon, 15 J 30 01/16 "Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea 32 01/16 "Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa This is the same thing you will see from a scan (see ). If you just run inc with no arguments it will look on your computer for email that is supposed to be coming to you. A lot of people like to use POP for grabbing their email. MH can do POP to grab your email. You will need to give inc a few command line arguments. &prompt.user; inc -host mail.pop.org -user username -norpop That tells inc to go to mail.pop.org to download your email, and that your username on their system is username. The option tells inc to use plain POP3 for downloading your email. MH has support for a few different dialects of POP. More than likely you will never ever need to use them though. While you can do more complex things with inc such as audit files and scan format files this will get you going. The msgchk command is used to get information on whether or not you have new email. msgchk takes the same and options that inc takes. <command>show</command>, <command>next</command> and <command>prev</command>—displaying and moving through email show is to show a letter in your current folder. Like inc, show is a fairly straightforward command. If you just type show and hit return then it displays the current message. You can also give specific message numbers to show: &prompt.user; show 32 45 56 This would display message numbers 32, 45 and 56 right after each other. Unless you change the default behavior show basically just does a more on the email message. next is used to move onto the next message and prev will go to the previous message. Both commands have an implied show command so that when you go to the next message it automatically displays it. <command>scan</command>—shows you a scan of your messages scan will display a brief listing of the messages in your current folder. This is an example of what the scan command will give you. 30+ 01/16 Jordan K. Hubbar Re: FBSD 2.1<<> Do you want a library instead of 31 01/16 Bruce Evans Re: location of bad144 table<<>> >It would appea 32 01/16 Jordan K. Hubbar Re: video is up<<> Anyway, mrouted won't run, ev 33 01/16 Michael Smith Re: FBSD 2.1<<Nate Williams stands accused of sa Like just about everything in MH this display is very configurable. This is the typical default display. It gives you the message number, the date on the email, the sender, the subject line, and a sentence fragment from the very beginning of the email if it can fit it. The + means that message is the current message, so if you do a show it will display that message. One useful option for scan is the option. This will list your messages with the highest message number first and lowest message number last. Another useful option with scan is to have it read from a file. If you want to scan your incoming mailbox on FreeBSD without having to inc it you can do scan -file /var/mail/username. This can be used with any file that is in the mbox format. <command>rmm</command> and <command>rmf</command>—remove the current message or folder rmm is used to remove a mail message. The default is typically to not actually remove the message but to rename the file to one that is ignored by the MH commands. You will periodically need to go through and physically delete the removed messages. The rmf command is used to remove folders. This does not just rename the files but actually removes the from the hard drive so you should be careful when you use this command. A typical session of reading with MH The first thing that you will want to do is inc your new mail. So at a shell prompt just type in inc and hit return. &prompt.user; inc Incorporating new mail into inbox... 36+ 01/19 Stephen L. Lange Request...<<Please remove me as contact for pind 37 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl 38 01/19 Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In &prompt.user; This shows you the new email that has been added to your mailbox. So the next thing to do is show the email and move around. &prompt.user; show Received: by sashimi.wwa.com (Smail3.1.29.1 #2) id m0tdMZ2-001W2UC; Fri, 19 Jan 96 13:33 CST Date: Fri, 19 Jan 1996 13:33:31 -0600 (CST) From: "Stephen L. Lange" <stvlange@wwa.com> To: matt@garply.com Subject: Request... Message-Id: <Pine.BSD.3.91.960119133211.824A-100000@sashimi.wwa.com> Mime-Version: 1.0 Content-Type: TEXT/PLAIN; charset=US-ASCII Please remove me as contact for pindat.com &prompt.user; rmm &prompt.user; next Received: from localhost (localhost [127.0.0.1]) by whydos.lkg.dec.com (8.6.11/8 .6.9) with SMTP id RAA24416; Fri, 19 Jan 1996 17:56:48 GMT Message-Id: <199601191756.RAA24416@whydos.lkg.dec.com> X-Authentication-Warning: whydos.lkg.dec.com: Host localhost didn't use HELO pro tocol To: hsu@clinet.fi Cc: hackers@FreeBSD.org Subject: Re: kern/950: Two PCI bridge chips fail (multiple multiport ethernet boards) In-Reply-To: Your message of "Fri, 19 Jan 1996 00:18:36 +0100." <199601182318.AA11772@Sysiphos> X-Mailer: exmh version 1.5omega 10/6/94 Date: Fri, 19 Jan 1996 17:56:40 +0000 From: Matt Thomas <matt@lkg.dec.com> Sender: owner-hackers@FreeBSD.org Precedence: bulk This is due to a typo in pcireg.h (to which I am probably the guilty party). The rmm removed the current message and the next command moved me on to the next message. Now if I wanted to look at ten most recent messages so I could read one of them here is what I would do: &prompt.user; scan last:10 26 01/16 maddy Re: Testing some stuff<<yeah, well, Trinity has 27 01/17 Automatic digest NET-HAPPENINGS Digest - 16 Jan 1996 to 17 Jan 19 28 01/17 Evans A Criswell Re: Hey dude<<>From matt@tempest.garply.com Tue 29 01/16 Karl Heuer need configure/make volunteers<<The FSF is looki 30 01/18 Paul Stephanouk Re: [alt.religion.scientology] Raw Meat (humor)< 31 01/18 Bill Lenherr Re: Linux NIS Solaris<<--- On Thu, 18 Jan 1996 1 34 01/19 John Fieber Re: Stuff for the email section?<<On Fri, 19 Jan 35 01/19 support@foo.garpl [garply.com #1138] parlor<<Hello. This is the Ne 37+ 01/19 Matt Thomas Re: kern/950: Two PCI bridge chips fail (multipl 38 01/19 Amancio Hasty Jr Re: FreeBSD and VAT<<>>> Bill Fenner said: > In &prompt.user; Then if I wanted to read message number 27 I would do a show 27 and it would be displayed. As you can probably tell from this sample session MH is pretty easy to use and looking through emails and displaying them is fairly intuitive and easy. Folders and Mail Searching Anybody who gets lots of email definitely wants to be able to prioritize, stamp, brief, de-brief, and number their emails in a variety of different ways. MH can do this better than just about anything. One thing that we have not really talked about is the concept of folders. You have undoubtedly come across the folders concept using other email programs. MH has folders too. MH can even do sub-folders of a folder. One thing you should keep in mind with MH is that when you ran inc for the first time and it asked you if it could create a Mail directory it began storing everything in that directory. If you look at that directory you will find a directory named inbox. The inbox directory houses all of your incoming mail that has not been thrown anywhere else. Whenever you create a new folder a new directory is going to be created underneath your MH Mail directory, and messages in that folder are going to be stored in that directory. When a new email message comes, it is thrown into your inbox directory with a file name that is equivalent to the message number. So even if you did not have any of the MH tools to read your email you could still use standard &unix; commands to munge around in those directories and just more your files. It is this simplicity that really gives you a lot of power with what you can do with your email. Just as you can use message lists like 23 16 42 with most MH commands there is a folder option you can specify with just about every MH command. If you do a scan +freebsd it will scan your freebsd folder, and your current folder will be changed to freebsd. If you do a show +freebsd 23 16 42, show is going to switch to your freebsd folder and display messages 23, 16 and 42. So remember that syntax. You will need to make sure you use it to make commands process different folders. Remember you default folder for mail is inbox so doing a folder +inbox should always get you back to your mail. Of course, in MH's infinite flexibility this can be changed but most places have probably left it as inbox. <command>pick</command>—search email that matches certain criteria pick is one of the more complex commands in the MH system. So you might want to read the pick1 man page for a more thorough understanding. At its simplest level you can do something like &prompt.user; pick -search pci 15 42 55 56 57 This will tell pick to look through every single line in every message in your current folder and tell you which message numbers it found the word pci in. You can then show those messages and read them if you wish or rmm them. You would have to specify something like show 15 42 55-57 to display them though. A slightly more useful thing to do is this: &prompt.user; pick -search pci -seq pick 5 hits &prompt.user; show pick This will show you the same messages you just did not have to work as hard to do it. The option is really an abbreviation of and pick is just a sequence which contains the message numbers that matched. You can use sequences with just about any MH command. So you could have done an rmm pick and all those messages would be removed instead. You sequence can be named anything. If you run pick again it will overwrite the old sequence if you use the same name. Doing a pick -search can be a bit more time consuming than just searching for message from someone, or to someone. So pick allows you to use the following predefined search criteria: search based upon who the message is to search based on who is in the Cc: list search for who sent the message search for emails with this subject find emails with a matching date search for any other component in the header. (i.e. to find all emails with a certain reply-to in the header) This allows you to do things like &prompt.user; pick -to freebsd-hackers@FreeBSD.org -seq hackers to get a list of all the email send to the FreeBSD hackers mailing list. pick also allows you to group these criteria in different ways using the following options: … … … … … … These commands allow you to do things like &prompt.user; pick -to freebsd-hackers -or -cc freebsd-hackers That will grab all the email in your inbox that was sent to freebsd-hackers or cc'd to that list. The brace options allow you to group search criteria together. This is sometimes very necessary as in the following example &prompt.user; pick -lbrace -to freebsd-hackers -and -not -cc freebsd-questions -rbrace -and -subject pci Basically this says pick (to freebsd-hackers and not cc'd on freebsd-questions) and the subject is pci. It should look through your folder and find all messages sent to the freebsd-hackers list that are not cc'd to the freebsd-questions list and contain pci in the subject line. Ordinarily you might have to worry about something called operator precedence. Remember in math how you evaluate from left to right and you do multiplication and division first and addition and subtraction second? MH has the same type of rules for pick. It is fairly complex so you might want to study the manual page. This document is just to help you get acquainted with MH. <command>folder</command>, <command>folders</command>, <command>refile</command>—three useful programs for folder maintenance There are three programs which are primarily just for manipulating your folders. The folder program is used to switch between folders, pack them, and list them. At its simplest level you can do a folder +newfolder and you will be switched into newfolder. From there on out all your MH commands like comp, repl, scan, and show will act on that newfolder folder. Sometimes when you are reading and deleting messages you will develop holes in your folders. If you do a scan you might just see messages 34, 35, 36, 43, 55, 56, 57, 80. If you do a folder -pack this will renumber all your messages so that there are no holes. It does not actually delete any messages though. So you may need to periodically go through and physically delete rmm'd messages. If you need statistics on your folders you can do a folders or folder -all to list all your folders, how many messages they have, what the current message is in each one and so on. This line of stats it displays for all your folders is the same one you get when you change to a folder with folder +foldername. A folders command looks like this: Folder # of messages ( range ); cur msg (other files) announce has 1 message ( 1- 1). drafts has no messages. f-hackers has 43 messages ( 1- 43). f-questions has 16 messages ( 1- 16). inbox+ has 35 messages ( 1- 38); cur= 37. lists has 8 messages ( 1- 8). netfuture has 1 message ( 1- 1). out has 31 messages ( 1- 31). personal has 6 messages ( 1- 6). todo has 58 messages ( 1- 58); cur= 1. TOTAL= 199 messages in 13 folders. The refile command is what you use to move messages between folders. When you do something like refile 23 +netfuture message number 23 is moved into the netfuture folder. You could also do something like refile 23 +netfuture/latest which would put message number 23 in a subfolder called latest under the netfuture folder. If you want to keep a message in the current folder and link it you can do a refile -link 23 +netfuture which would keep 23 in your current inbox but also list in your netfuture folder. You are probably beginning to realize some of the really powerful things you can do with MH. Sending Mail Email is a two way street for most people so you want to be able to send something back. The way MH handles sending mail can be a bit difficult to follow at first, but it allows for incredible flexibility. The first thing MH does is to copy a components file into your outgoing email. A components file is basically a skeleton email letter with stuff like the To: and Subject: headers already in it. You are then sent into your editor where you fill in the header information and then type the body of your message below the dashed lines in the message. When you leave the editor, the whatnow program is run. When you are at the What now? prompt you can tell it to send, list, edit, push, and quit. Most of these commands are self-explanatory. So the message sending process involves copying a component file, editing your email, and then telling the whatnow program what to do with your email. <command>comp</command>, <command>forw</command>, <command>reply</command>—compose, forward or reply to a message to someone The comp program has a few useful command line options. The most important one to know right now is the option. When MH is installed the default editor is usually a program called prompter which comes with MH. It is not a very exciting editor and basically just gets the job done. So when you go to compose a message to someone you might want to use comp -editor /usr/bin/vi or comp -editor /usr/local/bin/pico instead. Once you have run comp you are in your editor and you see something that looks like this: To: cc: Subject: -------- You need to put the person you are sending the mail to after the To: line. It works the same way for the other headers also, so you would need to put your subject after the Subject: line. Then you would just put the body of your message after the dashed lines. It may seem a bit simplistic since a lot of email programs have special requesters that ask you for this information but there really is no point to that. Plus this really gives you excellent flexibility. To:freebsd-rave@FreeBSD.org cc: Subject:And on the 8th day God created the FreeBSD core team -------- Wow this is an amazing operating system. Thanks! You can now save this message and exit your editor. You will see the What now? prompt and you can type in send or s and hit return. Then the FreeBSD core team will receive their just rewards. As I mentioned earlier, you can also use other commands at the What now? prompt. For example you can use quit, if you do not want to send the message. The forw command is stunningly similar. The big difference being that the message you are forwarding is automatically included in the outgoing message. When you run forw it will forward your current message. You can always tell it to forward something else by doing something like forw 23 and then message number 23 will be put in your outgoing message instead of the current message. Beyond those small differences forw functions exactly the same as comp. You go through the exact same message sending process. The repl command will reply to the current message, unless you give it a different message to reply to. repl will do its best to go ahead and fill in some of the email headers already. So you will notice that the To: header already has the address of the recipient in there. Also the Subject: line will already be filled in. You then go about the normal message composition process and you are done. One useful command line option to know here is the option. You can use all, to, cc, me after the option to have repl automatically add the various addresses to the Cc: list in the message. You have probably noticed that the original message is not included. This is because most MH setups are configured to do this from the start. <filename>components</filename>, and <filename>replcomps</filename>—components files for <command>comp</command> and <command>repl</command> The components file is usually in /usr/local/lib/mh. You can copy that file into your MH Mail directory and edit to contain what you want it to contain. It is a fairly basic file. You have various email headers at the top, a dashed line and then nothing. The comp command just copies this components file and then edits it. You can add any kind of valid RFC822 header you want. For instance you could have something like this in your components file: To: Fcc: out Subject: X-Mailer: MH 6.8.3 X-Home-Page: http://www.FreeBSD.org/ ------- MH would then copy this components file and throw you into your editor. The components file is fairly simple. If you wanted to have a signature on those messages you would just put your signature in that components file. The replcomps file is a bit more complex. The default replcomps looks like this: %(lit)%(formataddr %<{reply-to}%?{from}%?{sender}%?{return-path}%>)\ %<(nonnull)%(void(width))%(putaddr To: )\n%>\ %(lit)%(formataddr{to})%(formataddr{cc})%(formataddr(me))\ %<(nonnull)%(void(width))%(putaddr cc: )\n%>\ %<{fcc}Fcc: %{fcc}\n%>\ %<{subject}Subject: Re: %{subject}\n%>\ %<{date}In-reply-to: Your message of "\ %<(nodate{date})%{date}%|%(pretty{date})%>."%<{message-id} %{message-id}%>\n%>\ -------- It is in the same basic format as the components file but it contains quite a few extra formatting codes. The %(lit) command makes room for the address. The %(formataddr) is a function that returns a proper email address. The next part is %< which means if and the {reply-to} means the reply-to field in the original message. So that might be translated this way: %<if {reply-to} the original message has a reply-to then give that to formataddr, %? else {from} take the from address, %? else {sender} take the sender address, %? else {return-path} take the return-path from the original message, %> endif. As you can tell MH formatting can get rather involved. You can probably decipher what most of the other functions and variables mean. All of the information on writing these format strings is in the MH-Format manual page. The really nice thing is that once you have built your customized replcomps file you will not need to touch it again. No other email program really gives you the power and flexibility that MH gives you.
diff --git a/en_US.ISO8859-1/articles/pxe/article.sgml b/en_US.ISO8859-1/articles/pxe/article.sgml index 0daddba58e..c1b75586ed 100644 --- a/en_US.ISO8859-1/articles/pxe/article.sgml +++ b/en_US.ISO8859-1/articles/pxe/article.sgml @@ -1,294 +1,294 @@ %man %authors; %misc; %trademarks; ]>
FreeBSD Jumpstart Guide Alfred Perlstein
alfred@FreeBSD.org
 $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.intel; &tm-attrib.general; This article details the method used to allow machines to install FreeBSD using the &intel; PXE method of booting a machine over a network. Introduction This procedure will make the Server both insecure and dangerous, it is best to just keep the Server on its own hub and not in any way accessible by any machines other than the Clients. Terminology: Server The machine offering netboot and install options. Client The machine that will have FreeBSD installed on it. Requires: Clients supporting the &intel; PXE netboot option, an Ethernet connection. Please let me know if you come across anything you have problems with or suggestions for additional documentation. If you would like someone to train/implement a specific netinstall system for you, please send email so that we can discuss terms. I would also like to thank &a.ps; and &a.jhb; for doing most of the programming work on pxeboot, the interface to the &intel; PXE (netboot) system. Server Configuration Install DHCP: Install net/isc-dhcp3 you can use this config file dhcpd.conf, stick it in /usr/local/etc/ Enable tftp: Make a directory /usr/tftpboot Add this line to your /etc/inetd.conf: tftp dgram udp wait nobody /usr/libexec/tftpd tftpd /usr/tftpboot Enable NFS: Add this to /etc/rc.conf: nfs_server_enable="YES" Add this to /etc/exports: /usr -alldirs -ro Reboot to enable the new services or start them manually. Bootstrap Setup Download bootfiles: Download the kern.flp and mfsroot.flp floppy images. - Setup tftp/pxe-boot directory: + Set up tftp/pxe-boot directory: Put pxeboot in the boot directory: &prompt.root; rm -rf /usr/obj/* &prompt.root; cd /usr/src/sys/boot &prompt.root; make &prompt.root; cp /usr/src/sys/boot/i386/pxeldr/pxeboot /usr/tftpboot Using the vndevice mount the kern.flp file and copy its contents to /usr/tftpboot: &prompt.root; vnconfig vn0 kern.flp # associate a vndevice with the file &prompt.root; mount /dev/vn0 /mnt # mount it &prompt.root; cp -R /mnt /usr/tftpboot # copy the contents to /usr/tftpboot &prompt.root; umount /mnt # unmount it &prompt.root; vnconfig -u vn0 # disassociate the vndevice from the file Compile a custom kernel for the clients (particularly to avoid the device config screen at boot) and stick it in /usr/tftpboot. Make a special loader.rc to and install it in /usr/tftpboot/boot/loader.rc so that it does not prompt for the second disk, here is mine. Extract the installer and helper utilities from the mfsroot disk and uncompress them, put them in /usr/tftpboot as well: &prompt.root; vnconfig vn0 mfsroot.flp # associate a vndevice with the file &prompt.root; mount /dev/vn0 /mnt # mount it &prompt.root; cp /mnt/mfsroot.gz /usr/tftpboot # copy the contents to /usr/tftpboot &prompt.root; umount /mnt # unmount it &prompt.root; vnconfig -u vn0 # disassociate the vndevice from the file &prompt.root; cd /usr/tftpboot # get into the pxeboot directory &prompt.root; gunzip mfsroot.gz # uncompress the mfsroot Make your sysinstall script install.cfg, you can use mine as a template, but you must edit it. Copy the sysinstall script into the extracted and uncompressed mfsroot image: &prompt.root; cd /usr/tftpboot &prompt.root; vnconfig vn0 mfsroot &prompt.root; mount /dev/vn0 /mnt &prompt.root; cp install.cfg /mnt &prompt.root; umount /mnt &prompt.root; vnconfig -u vn0 Install Setup Put the install files in an NFS accessible location on the Server. Make a directory corresponding the 'nfs' directive in the install.cfg file and mirror the FreeBSD install files there, you will want it to look somewhat like this: ABOUT.TXT TROUBLE.TXT compat20 floppies ports ERRATA.TXT UPGRADE.TXT compat21 games proflibs HARDWARE.TXT XF86336 compat22 info src INSTALL.TXT bin compat3x kern.flp LAYOUT.TXT catpages crypto manpages README.TXT cdrom.inf dict mfsroot.flp RELNOTES.TXT compat1x doc packages Copy the compressed packages into the packages/All directory under nfs. Make sure you have an INDEX file prepared in the packages directory. You can make your own INDEX entries like so: alfred-1.0||/|Alfred install bootstrap||alfred@FreeBSD.org|||| Then you can install custom packages, particularly your own custom post-install package. Custom Post-Install Package You can use the script pkgmaker.sh to create a custom package for post install, the idea is to have it install and configure any special things you may need done. pkgmaker is run in the directory above the package you wish to create with the single argument of the package (ie mypkg) which will then create a mypkg.tgz for you to include in your sysinstall package. Inside your custom package dir you will want a file called PLIST which contains all the files that you wish to install and be incorporated into your package. You will also want files called pre and post in the directory, these are shell scripts that you want to execute before and after your package is installed. Since this package is in your install.cfg file it should be run and do the final configuration for you.
diff --git a/en_US.ISO8859-1/articles/pxe/post b/en_US.ISO8859-1/articles/pxe/post index 9db1f27ebd..b465f55008 100644 --- a/en_US.ISO8859-1/articles/pxe/post +++ b/en_US.ISO8859-1/articles/pxe/post @@ -1,36 +1,36 @@ #!/bin/sh # $Wintelcom: src/freebsd/pxe/doc/post,v 1.1 2000/07/14 12:42:05 bright Exp $ # $FreeBSD$ echo post-install set PATH=/bin:/usr/local/bin:/sbin:/usr/sbin:/usr/bin:/usr/bin/X11 export PATH # do timezone cp /usr/share/zoneinfo/America/Los_Angeles /etc/localtime conf="/etc/rc.conf.local" rm $conf echo 'sendmail_enable="NO"' >> $conf echo 'dumpdev="/dev/ad0s1b"' >> $conf echo 'sshd_enable="YES"' >> $conf echo 'linux_enable="YES"' >> $conf -# setup IP address and hostname +# set up IP address and hostname if=`ifconfig fxp1 inet | grep '[ ]*inet' | sed 's/[ ]*//'` echo "ifconfig_fxp1=\"${if}\"" >> $conf name=`echo $if | sed 's/[ ][ ]*/ /g' | cut -f2 -d" " | cut -f4 -d.` echo "hostname=\"suyy${name}\"" >> $conf echo "network_interfaces=\"fxp0 fxp1 lo0\"" >> $conf -# setup gateway, parse netstat output +# set up gateway, parse netstat output gw=`netstat -rn | grep '^default' | sed 's/[ ][ ]*/ /g' | cut -f2 -d" "` echo "defaultrouter=\"${gw}\"" >> $conf pwd_mkdb -p /etc/master.passwd exit 0 diff --git a/en_US.ISO8859-1/articles/releng-packages/article.sgml b/en_US.ISO8859-1/articles/releng-packages/article.sgml index e57e8fe953..9e7ec3070e 100644 --- a/en_US.ISO8859-1/articles/releng-packages/article.sgml +++ b/en_US.ISO8859-1/articles/releng-packages/article.sgml @@ -1,375 +1,375 @@ %man; %teams; %freebsd; %authors; %trademarks; ]>
FreeBSD Release Engineering for Third Party Software Packages Steve Price
steve@FreeBSD.org
 $FreeBSD$ &tm-attrib.freebsd; &tm-attrib.intel; &tm-attrib.xfree86; &tm-attrib.general; This paper describes the approach used by the FreeBSD release engineering team to produce a high quality package set suitable for official FreeBSD release media. This document is a work in progress, but eventually it will cover the process used to build a clean package set on the FreeBSD.org Ports Cluster, how to configure any other set of machines as a ports cluster, how to split up the packages for the release media, and how to verify that a package set is consistent. Building packages from the Ports Collection The FreeBSD Ports collection is a collection of over &os.numports; third-party software packages available for FreeBSD. The &a.portmgr; is responsible for maintaining a consistent ports tree that can be used to create the binary packages that accompany a given FreeBSD release. The Ports Cluster In order to provide a consistent set of third-party packages for FreeBSD releases, every port is built in a separate chroot environment, starting with an empty /usr/local and /usr/X11R6. The requisite dependencies are installed as packages before the build proceeds. This enforces consistency in the package build process. By starting the package build in a pristine environment, we can assure that the package metadata (such as required dependencies) is accurate. This way, we will never generate packages that might work on some systems and not on others depending on what software was previously installed. The Ports Cluster for the x86 architecture currently consists of a master node (Dual &pentium; III 733MHz) and 8 slave nodes (&pentium; III 800MHz) to do the actual package builds. With this configuration, a complete package build takes over 24 hours. These machines are co-located with the other FreeBSD Project equipment at Yahoo's corner of Exodus in Santa Clara, CA. The Ports Cluster for the Alpha architecture consists of 7 PWS 500A machines donated by Compaq and also co-located with Yahoo's facilities. The Package Split For FreeBSD 4.4 over 4.1 gigabytes of packages were created. This causes a problem for CDROM distributions because we would like to ship as many packages as possible without making the user insert another disc to satisfy dependencies. The solution is to create clusters of like packages with similar dependencies and group these onto specific discs. This section describes the software and methodology used to create those package sets for the official FreeBSD release discs. The scripts and other files needed to produce a package split can be found in the CVS tree in ports/Tools/scripts/release. Copy this directory to a machine that has enough free disk space to hold 2 to 3 times the size of the package set that you wish to split. The following scripts are present in this directory: config This file contains the free space on each disc and whether packages, distfiles, or both are allowed on any given disc. The first column is the disc name. It must be - of the form disc[0-9a-z]. Currently it is setup + of the form disc[0-9a-z]. Currently it is set up to allow for 10 discs (4 for the release set and 6 for the toolkit). There is an implied extra disc called scratch where all of the remaining distfiles/packages land if they do not fit elsewhere. The second column can be either a 1 or 0, where 1 says that it is okay to place packages on this disc. The third column works the same way, but it controls whether distfiles are placed on this disc. The last column denotes the number of bytes of free space on a disc. doit.sh This is the workhorse. Once you have all the files in place and things properly configured this script directs the process of splitting packages. Beware it is interactive so you need to keep an eye on it as it runs. More details on what happens in this script will follow. checkdeps.pl Makes sure all packages dependencies are satisfied given an INDEX file and a directory of packages. oneshot.pl This is where all the magic (and I use that term loosely as it is mostly just a brute force approach) happens. Given a list of required packages for each disc and a set of packages/distfiles this is the script that places a package or distfile on a disc along with all of its dependencies. print-cdrom-packages.sh This file is a copy of src/release/scripts/print-cdrom-packages.sh from the release you are working on. scrubindex.pl This script removes lines from an INDEX file for packages that are not present. It also removes the &xfree86; dependencies. NOTE: you will need to tweak the value of the xdep variable to make sure the version number is correct. setup.sh This is a helper script that I use on the bento cluster to grab a copy of the ports tree and the matching set of the packages/distfiles. Here is a checklist of things you will need to check or configure before going any further. Edit config to denote the number of discs you have, their sizes, and whether you want them want to contain packages, distfiles, both, or neither. Make sure you remove the gen directory if there is an old one laying around. This directory contains working files that will only be valid for the current split. On your first pass through a split it is best to fake the copying of packages and distfiles. This will save both time and diskspace while you do a couple of trial runs to make sure things fit, etc. In the oneshot.pl set the fake variable to 1 and instead of actually copying the files it will &man.touch.1; them. Be sure you turn this off or set fake to 0 before you give the resultant discs to the person that will be mastering the discs otherwise they will get a directory full of zero-sized files. Make sure you have a recent copy of the print-cdrom-packages.sh and that it is from the correct release. Check to make sure the &xfree86; dependency in scrubindex.pl has the correct version number. You will also need to make sure this value is correct in doit.sh as well. Next you will need to get a copy of the ports tree, packages, and distfiles from a recent build on the package cluster. See the setup.sh for a working example but essentially here is what needs to be done. Grab a copy of ports.tar.gz and extract it into the ports directory alongside doit.sh and the scripts directory. Remove the packages/distfiles directories or symlinks. Bento has these as symlinks and you will have mixed results if you do not get rid of them before proceeding. Create a new ports/packages directory and copy the package set from the package building cluster. Create a new ports/distfiles directory and copy the distfiles from the package building cluster. NOTE: if you do not want any distfiles simply create the directory and leave it empty. This directory must be present even if it does not contain anything. Now we are finally ready for the fun task of actually splitting the packages. You start the processing by running ./doit.sh. Here is what it does the first time you run it. Create a list of the restricted (can not be on the master FTP site) ports. Asks you if you would like to remove the restricted ports. Most of the time you will want to answer (y)es here. Create a list of the packages/distfiles that can not be put on the discs. Asks you if you would like to remove the non-cdromable packages/distfiles. Most of the time you will want to answer (y)es here. Copies the INDEX from the ports directory to the gen directory. In doing so it removes the lines for ports where the packages do not exist. It also checks to make sure that all of the required dependency packages are present. Create a list of packages that are required on each disc. Asks you if you would like to populate the discs. After populating each disc it will check for missing dependencies, scrub the INDEX file, and create the CHECKSUM.MD5 file. Check to make sure the required packages made it on each disc and gives you a summary of the sizes of each disc. After going through this the first time if you are lucky enough that all of the required packages built and fit on each disc. All you need to do is set fake to 0 in oneshot.pl and re-run ./doit.sh. The second and subsequent times around it will skip steps 1-5 above. If you want to re-run any of those steps refer to doit.sh for which files need to be removed to not short-circuit those steps. If you want to repeat all of these steps then the easiest way is to rm -rf gen. Upon successful completion the packages/distfiles will be in the disc* directories and the leftover will be in the scratch directory. What to do if things go wrong? Here is some common gotchas and workarounds. Missing required packages This is a pretty common occurrence. You will either need to wait for a new set of packages where the missing packages were built or get someone to re-start the package build for you. Do not attempt to build the missing packages on your own machine and add them into the fray. While you might be able to get away with this if you are extremely careful the vast majority of the time you will miss some little detail and the simple process of adding a package could make hundreds of others come up mysteriously broken. Required packages will not fit This happens on occasion too and is relatively easy to fix. Simply edit print-cdrom-packages.sh to move packages around until they fit. Yes this is an iterative process and one of the reasons why you should enable fake in oneshot.pl until you have gotten things the way you want them. Re-run ./doit.sh after you made your adjustments. Required packages not on the right (or any) disc This usually means you did not add them to print-cdrom-packages.sh or you put them on the wrong disc. This script is the gospel by which this whole process determines where a package must be. If you want to force a package to land on a particular disc this is the only way to ensure that it will happen. If you get completely stuck and can not figure out why things are borked or how to fix them then email &a.steve; for assistance.