Taking control

Users and groups; The super user; Processes; Daemons; Stopping processes; Timekeeping; Log files; Multiple processor support; PC Card devices; Emulating other systems; Emulating Linux; Emulating SCO UNIX; Emulating Microsoft Windows;

In Chapter 7 we saw the basics of working with FreeBSD. In this part of the book, we'll look at some more system-specific issues. This chapter discusses the following topics:

• • UNIX is a muki-user operating system. We've already skimmed over creating user accounts, but on page 144 we'll look at it in more detail
• • Not all users are created equal In particular, the system administration login root has power overall other users. We'll look at root on page 146.
• • UNIX implements multi-tasking via a mechanism called processes. We’ll look at them on page 148.
• • Timekeeping is extremely important in a networking system. If your system has the wrong time, it can cause all sorts of strange effects. On page 155 we'll look at how to ensure that your system is running the correct time.
• • A number of events are of interest in keeping a machine running smoothly. The system can help by keeping track of what happens. One mechanism for this is log files files that contain information about what has happened on the machine. We'll look at them on page 157.
• • On page 159, we'll look at how FreeBSD handles systems with more than one processor. This is also called Symmetrical Multi-Processor or SMP support.
• • Nearly every modem laptop has as special bus for plugin cards. It used to be called PCMCIA an acronym for the rather unlikely name Personal Computer Memory Card International Association. Nowadays it's called PC Card. It was later upgraded to a 32 bit bus called CardSus We'll look at how FreeBSD supports PC Card and CardBus on page 159.
• • Starting on page 162, we'll look at FreeBSD's support for emulating other operating systems.
• • Other aspects of FreeBSD are so extensive that we'll dedicate separate chapters to them. We'll look at them in Chapters 9 to 15.
• • Starting and stopping the system is straightforward, but there are a surprising number of options. Many of them are related to networking, so Chapter 29 is located after the networking section.

G. Lehey FreeBSD Operating System

Users and groups

We've already looked at users in Chapter 7. In this chapter, well take a deeper look.

In traditional UNIX, information about users was kept in the file /etc/passwd. As the name suggests, it included the passwords, which were stored in encrypted form. Any user could read this file, but the encryption was strong enough that it wasn't practical to decrypt the passwords. Nowadays processors are much faster, and it's too easy to crack a password. As a result, FreeBSD keeps the real information in a file called /etc/mas-ter.passwd, and for performance reasons it also makes it available in database form in /etc/pwd.db and /etc/spwd.db. None of these file are user-readable, /etc/passwd remains for compatibility reasons: some third-party programs access it direcdy to get information about the environment in which they are running.

Choosing a user name

So what user name do you choose? User names are usually related to your real name and can be up to eight characters long. Like file names, they’re case-sensitive. By convention, they are in all lower case, even when they represent real names. Typical ways to form a user name are:

• • First name. In my personal case, this would beg reg.
• • Last name lehey
• • First name and initial of last name g r e g 1
• • Initial of first name, and last name g 1 e h e ó
• • Initials gpl
• • Nickname (for example, grog)

I choose the last possibility, as we will see in the following discussion.

Adding users

We've already seen how to use sysinstall to create a user. It's not the only way. There are at least two other methods. One is the program adduser:

G. Lehey FreeBSD Operating System

# adduser

Use option "-verbose" if you want see more warnings & questions or try to repai

Enter username [a-zO-9]: yana

Enter full name []: Yana Lehey

Enter shell bash csh date no sh [bash]: accept the default

Uid [1000]: accept the default

Enter login class: default []: accept the default

Login group yana [yana]: home

Login group is "home". Invite yana into other groups: no

An alternative way of adding or removing users is with the vipw program. This is a more typical UNIX-hackish approach: vipw starts your favorite editor and allows you to edit the contents of the file /etc/master.passwd. After you have finished; it checks the contents and rebuilds the password database. Figure 8-1 shows an example.

:OiO:Secure Shell Daemon;/var/empty:/sbin/nologin

: :0:0:6endmai 1 Submission Useri/var/spool/cl ientmqueuei/sbin/nologin

:0;0;Sendmai1 Default User:/var/spool/mqueue;/sbin/nologin

Bind Sandbox;/:/sbin/nologin

:UUCP pseudo-useri/var/spool/uucppublict/usr/libexec/uucp/uucico : X-10 daemon : Zusr/1 oca 1 Zxten:Zsb i nZnolog i n

:26;:

:0:0:

:0:0:

:0;0:

neids;*:8:8:;0:0;Neii)s Subsystem:/:/sbin/nologin

man:*;9:9::0:0;Mister Man Pages:/usrZshareZman;ZsbinZnologin

sshd:*;22;22::' ' * - -- - ....

smmsp;*:25:25:

mailnull;*:26:

bind;*;53:53::

uucp:*:66;66::

xten:*:67:67::

pop:*:68:6::0:0:Post Office Owner:Znonexistent:ZsbinZnologin

www:*:80;80::0:0:Uorld Wide Web Ouner:/nonexistent:/sbin/nologin

nobody: *i65534;65534::0:0:Unprivi leged user;Znonexistent: /sbin/nologi n

3iane:$l$calliJhjY$69SVPd5TVNhSioYsVnsuW/:1001:1001::0:0;User &:/home/diane:/usr/local/bin/bash

grog;$l$crXRlVxu$U3AZ8ACF5ZLA2U0ElYqm.0:1004; 1000:root:0:0:Greg 'groggy' Lehey,Echunga SA, +61-8-8388-8286,+61-8-8388-825® fi 0: /home/grog;/usr/1 oca 1 Zb i n/bash

óvonne: $l$BaTr50fBJyZpEkOpCAnROfc41e i tsKZ: 1005:1001:: 0; 0: Yvonne Lehey, Echunga, +61-8-8388-8250; ZhomeZyvonne: ZusrZ1 oca 1 / S fibin/bash

pw.YFTOTJ .(Fundamental Serverl~L22~Bpt-

[y Auto-saving,..done

Ðèñ. 8.1. Figure8-1: vipw display

You might be wondering why would you ever want to do things this way, and you might find it funny that most experienced UNIX administrators prefer it. The reason is that you get more of an overview than with a peephole approach that graphical environments give you, but of course you need to understand the format better. It's less confusing once you know that each line represents a single user, that the lines are divided into fields (which may be empty), and that each field is separated from the next by a colon (:). Table 8-1 describes the fields you see on the line on which the cursor is positioned. You can read more about the format of /etc/master.passwd in the man page passwd(5).

Òàáëèöà 8.1. /etc/master.passwd format

The super user

FreeBSD has a number of privileged users for various administration functions. Some are just present to be the owners of particular files, while others, such as daemon and uucp, exist to run particular programs. One user stands above all others, however: root may do just about anything. The kernel gives root special privileges, and you need to become root to perform a number of functions, including adding other users. Make sure root has a password if there is any chance that other people can access your system (this is a must if you have any kind of dialup access). Apart from that, root is a user like any other, but to quote the man page su(l):

By default (unless the prompt is reset by a startup file) the super user prompt is s<

Becoming super user

Frequently when you're logged in normally, you want to do something that requires you to be root. You can log out and log in again as root, of course, but there's an easier way:

$ su become super user

Password: as usual, it doesn't echo

# root prompt

To use su, you must be a member of the group wheel Normally you do this when

G. Lehey FreeBSD Operating System

you add the user, but otherwise just put the name of the user at the end of the line in/etc/group:

wheel:* :0 root, grog add the text in boldface

BSD treats su somewhat differendy from System V. First, you need to be a member of the group wheel, and secondly BSD gives you more of the super user environment than System V. See the man page for further information.

Having a single root password is a security risk on a system where multiple people know the password. If one of them leaves the project, you need to change the password. An alternative is the sudo port (/usr/ports/security/sudo). It provides fine-grained access to root privileges, all based on the user's own password. Nobody needs to know the root password. If a user leaves, you just remove his account, and that cancels his access.

Adding or changing passwords

If your system has any connection with the outside world, it's a good idea to change your password from time to time. Do this with the passwd program The input doesn't look very interesting:

$ passwd

Changing local password for yana.

Old password: doesn't echo

New password: doesn't echo

Retype new password: doesn't echo

passwd: rebuilding the database...

passwd: done

You have to enter the old password to make sure that some passer-by doesn't change it for you while you're away from your monitor, and you have to enter the new password twice to make sure that you don't mistype and lock yourself out ol your account. If this does happen anyway, you can log in as root and change the password: root doesn't have to enter the old password, and it can change anybody's password. For example:

# passwd yana

G. Lehey FreeBSD Operating System

Changing local password for yana.

New password: doesn't echo

Retype new password: doesn't echo

passwd: rebuilding the database...

passwd: done

In this case, you specify the name of the user for whom you change the password.

If you are changing the root password, be careful: it's easy enough to lock your self out of the system if you mess things up, which could happen if, for example, you mistyped the password twice in the same way (don't laugh, it happens). Il you're running X, open another window and use su to become root If you're running in character mode, select another virtual terminal and log in as root there. Only when you're sure you can still access root should you log out.

If you do manage to lose the root password, all may not be lost. Reboot the machine to single-user mode (see page 540), and enter:

# mount -u / mount root file system read/write

# mount /usr mount /usrfile system (if separate)

# passwd root change the password for root

Enter new password:

Enter password again:

# ^AD enter ctrl-D to continue with startup

If you have a separate /usr file system (the normal case), you need to mount it as well, since the pas s wd program is in the directory /usr/bin. Note that you should explicitly state the name root: in single-user mode, the system doesn't have the concept of user IDs.

Processes

As we have seen, UNIX is a multi-user, multi-tasking operating system In particular, you can run a specific program more than once. We use the term process to refer to a particular instance of a running program Each process is given a process ID more frequently referred to as PID a number between 0 and 9 9 9 9 9 that uniquely identifies it. There are many things that you might like to know about the processes that are currently running, such as:

• • How many processes are running?
• • Who is running the processes?
• • Why is the system so slow?
• • Which process is blocking my access to the modem?

Your primary tool for investigating process behavior is the ps (process status) command. It has a large number of command options, and it can tell you a whole lot of things that you will only understand when you have investigated how the kernel works, but it can be very useful for a number of things. Here are some typical uses:

What processes do I have running?

After starting a large number of processes in a number of windows under X, you probably can't remember what is still running? Maybe processes that you thought had stopped are still running. To display a brief summary of the processes you have running, use the ps command with no options: $ ps

PID TT STAT TIME COMMAND

• 187 pO Is+ 0:01.02 -bash (bash)
• 188 Pi Ss 0:00.62 -bash (bash)
• 453 Pi R+ 0:00.03 ps

This display shows the following information:

• • The PID of the process.
• • TT is short for teletype, and shows the last few letters of the name of thecontrolling terminal, the terminal on which the process is running. In this example, the terminals are /dev/ttypO and /dev/ttypL
• • S TAT shows the current process status. It's involved and requires a certain amount of understanding of how the kernel runs to interpret it—see the man page for ps for more details.
• • TIME is the CPU time that the process has used in minutes, seconds and hundredths of a second. Note that many other UNIX systems, particularly System V, only show this field to the nearest second.
• • COMMAND is normally the command you entered, but don't rely on this. In

G. Lehey FreeBSD Operating System

the next section, you'll see thatsendmafl has changed its COMMAND field to tell you what it is doing. You'll notice that the command on the last line is the ps that performs the listing. Due to some complicated timing issue in the kernel, this process may or may not appear in the listing.

What processes are running?

There are many more processes in the system than the list above shows. To show them all, use the a option to ps. To show daemons as well (see the next section for a definition of daemon), use the x option. To show much more detail, use the u or 1 options. For example:

$ ps waux

daemon 408 0.0 0.0 1136 152 ?? Ss 18DecO2 0:11.41 /usr/sbin/rwl

www 582 0.0 0.0 2432 8 ?? IW - 0:00.00 /usr/local/sbin/httj

G. Lehey FreeBSD Operating System

grog 608 0.0 0.1 1316 720 vO I 18DecO2 0:00.04 -bash (bash) root 2600 0.0 0.0 1180 8 vl IWs+ - 0:00.00 /usr/libexec/getty

root 33069 0.0 0.3 5352 1716 ?? Ss 29DecO2 0:01.30 xterm-name

grog 33081 0.0 0.1 1328 752 p8 Is+ 29DecO2 0:00.09 /usr/local/bir

This list is just an excerpt. Even on a freshly booted system, the real list of processes will be much larger, about 50 processes.

We've seen a number of these fields already. The others are:

• • USER is the real user ID of the process, the user ID of the person who started it.
• • % CPU is an approximate count of the proportion of CPU time that the process has been using in the last few seconds. This is the column to examine if things suddenly get slow.
• • %MEM is an approximate indication of the amount of physical memory that the process is using.
• • VS Z (virtual size) is the amount of virtual memory that the process is using, measured in kilobytes.
• • RS S (resident segment size) is the amount of physical memory currently in use, measured in kilobytes.
• • S TARTE D is the time or date when the process was started.

In addition, a surprising number of processes don't have a controlling terminal They are daemons and we'll look at them in the next section.

Daemons

A significant part of the work in a FreeBSD system is performed by daemons. A daemon is not just the BSD mascot described on page 21—it's also a process that goes around in the background and does routine work such as sending mail (sendmail), handling incoming Internet connections (inetd), or starting jobs at particular times (cron).

To quote the Oxford English Dictionary: Demon Also daemon. ME [In form and in sense I, a. L. dcemon (med. L. demon)...] la. In ancient Greek mythology ( = áàöëèè): A supernatural being of a nature intermediate between that of gods and men, an inferior divinity, spirit, genius (including the souls of deceased persons,

G. Lehey FreeBSD Operating System

esp deified heros). Often written dcemon for distinction.

You can recognize daemons inaps waux listing by the fact that they don't have a controlling terminal—instead you see the characters ? ? Each daemon has a man page that describes what it does.

Normally, daemons are started when the system is booted and run until the system is stopped. If you stop one by accident, you can usually restart them One exception is init, which is responsible for starting other processes. If you kill it, you effectively kill the system Unlike traditional UNIX systems, FreeBSD does not allow init to be killed.

cron

One of the more useful daemons is cron named after Father Time.cron performs functions at specific times. For example, the system runs the script /etc/periodic/daily every day at 2:00 am, the script /etc/periodic/weekly every Saturday at 3:30 am, and the script /etc/periodic/monthly on the first day of every month at 5:30 am

To tell cron to perform a function at a particular time, you need a file called a crontab. The system keeps the realcrontab where you can't get at it, but you can keep a copy. It's a good idea to call it crontab as well

Let's look at the format of the default systemcrontab, located in /etc/crontab:

# /etc/crontab - root's crontab for FreeBSD

#

# $Id: crontab, v 1.10 1995/05/27 01:55:21 ache Exp $

# From Id: crontab, v 1.6 1993/05/31 02:03:57 cgd Exp

#

SHELL=/bin/sh

PATH=/etc: /bin: /sbin: /usr/bin: /usr/sbin

HOME=/var/log

#

# minute hour mday month wday who command

#

*/5 * * * * _root /usr/libexec/atrun

G. Lehey

#

# rotate log files every hour, if necessary

#0 * * * * _root /usr/bin/newsyslog

# #do daily/weekly/monthly maintenance

• 0 2 * * * root /etc/dai]y 2>&1
• 30 3 ** 6 root /etc/weekly 2>&1
• 30 5 1 * * root /etc/monthly 2>&1

#

#time zone change adjustment for wall emos clock, #See adjkemtz (8) for details.

1,31 0-4 * * * _root /sbin/adjkemtz -a

As usual, lines starting with # are comments. The others have seven fields. The first five fields specify the minute, the hour, the day of the month, the month, and the day of the week on which an action should be performed. The character * means "every." Thus, 0 2 * * * (for/etc/daily) means " 0 minutes, 2 o’clock (on the 24 hour clock), every day of the month, every month, every weekday."

Field number six is special: it only exists in /etc/crontab, not in private crontabs. It specifies the user for whom the operation should be performed. When you write your own crontab file, don't use this field.

The remaining fields define the operation to be performed cron doesn't read your shell initialization files. In particular, this can mean that it won't find programs you expect it to find. It's a good idea to put in explicit PATH definitions, or specify an absolute pathname for the program, as is done in this example. Cron mails the output to you, so you should check root’s mail from time to time.

To install or list a crontab, use the crontab program:

$ crontab crontab install a crontab

$ crontab -1 list the contents of an installed crontab

#DO NOT EDIT THIS FILE - edit the master and reinstall

#(crontab installed on Wed Jan 115:15:10 1997)

#(Cron version — $Id: crontab.c,v 1.7 1996/12/17 00:55:12 pst Exp $)

00 * * */home/grog/S cripts/rotate- log

G. Lehey

Processes in FreeBSD Release 5

Some of the processes in the example above are specific to FreeBSD Release 5:

• FreeBSD Release 5 has an idle process to use up the excess processor time and perform certain activities needed when no process is active. This example machine has two processors, so there are two of them:

root 12 95.7 0.0 0 12 ?? RL lJan70 1406:43.85 (idle: cpuO) root 1195.1 0.0 0 12 ?? RL Uan70 1406:44.64 (idle:cpul)

• A number of the processes have names starting with irq or swi:

root 12 0.0 0.0 0

root 13 0.0 0.0 0

root 18 0.0 0.0 0

root 20 0.0 0.0 0

root 21 0.0 0.0 0

root 22 0.0 0.0 0

root 23 0.0 0.0 0

• 12 ?? WL Uan70
• 12 ?? WL Uan70
• 12 ?? WL lJan70
• 12 ?? WL Uan70
• 12 ?? WL Uan70
• 12 ?? WL Uan70
• 12 ?? WL Uan70
• 15:04.95 (swil:net)
• 21:30.29 (swi6:tty:s
• 0:00.00 (swi3:cambi
• 0:00.00 (irqll:ahc0
• 39:00.32 (irq5: r!0)
• 7:12.92 (irql4:ata0)
• 0:47.99 (irql5:atal)

These processes handle hardware interrupts (irq) or software interrupts (swi). The text which follows gives an idea of which devices or software services they support.

top

Another tool for investigating system performance is top, which shows a number of performance criteria, including the status of the processes are using the most resources. Start it with the number of processes you want displayed. Example 8-1 gives an example.

$ top -S 10

last pid: 3992; load averages: 0.59, 0.17, 0.06 up 0+23:54:49 17:25:13

87 processes: 3running, 73 sleeping, 8 waiting, 3 lock

CPU states: 10.2% user, 0.0% nice, 18.8% system, 1.7% interrupt, 69.4% idle Mem 43M Active, 36M Inact, 31M Wired, 7460K Cache, 22M Buf, 2996K F Swap: 512M Total, 512M Free

PID USER PRI NICE SIZE RES STATE C TIME WCPU CPU

• 12 root -16 Î OK 12K RUN Î 23.7H 55.32% 55.32% idle: cp
• 11 root -16 Î OK 12K CPU1 1 23.7H 54.49% 54.49% idle: cp
• 2854 grog 97 Î 4940K 3932K *Giant 1 0:04 3.88% 3.86% xterm
• 20 root -64 -183 OK 12K WAIT 1 0:08 0.83% 0.83% irql4:at
• 2925 root 96 0 712K 608K select 1 0:01 0.15% 0.15% make
• 3193 grog 96 0 2220K 1304K CPU0 0 0:01 0.15% 0.15% top
• 3783 root 96 0 520K 416K select 1 0:00 0.10% 0.05% make
• 167 root 96 0 13876K 2112K select 0 1:02 0.00% 0.00% xcpusta
• 25 root -68 -187 OK 12K WAIT 0 0:28 0.00% 0.00% irq9:xl0
• 110 root 96 0 1528K 956K select 1 0:26 0.00% 0.00% ntpd

Figure8-2: top display

By default, the display is updated every two seconds and contains a lot of information about the system state:

• • The first line gives information about the last PID allocated (you can use this to follow the number of processes being created) and the load average, which gives information about how many processes are waiting to be scheduled.
• • The next line gives an overview of process statistics, and in what state they are. A process waits for external events to complete; it waits on a lock if some other process has a kernel resource which it wants.
• • The third line shows the percentage of time used in user mode, in system (kernel) mode and by interrupts.
• • The fourth line shows memory usage.
• • The fifth line shows swap statistics. When swapping activity occurs, it also appears on this line.
• • The remaining lines show the ten most active processes (because the parameter 10 was specified on the command line). The -S option tells top to include system processes, such as the idle and the interrupt processes. The state can be:
• • RUN, when the process is waiting for a processor to run on.
• • CPUOorCPUl, when the process is actively executing.
• • *lock, where lock is the name of a kernel lock. In this example, the xterm is waiting on the lock Giant.
• • A wait string, which indicates an event on which the process is waiting. See the man page top (1) for more details.

Stopping processes

Sometimes you may find that you want to stop a currently running process. There are a number of ways to do this, but the easiest are:

• • If the process is running on a terminal, and it's accepting input, hitting the EOF key (usually Ctrl-D) will often do it.
• • If EOF doesn't do it, try the INTR key (usually Ctrl-C).
• • If the process is ignoring INTR, or if it is not associated with a terminal, use the kill command. For example, to find who is using all the CPU time, use ps and look at the % CPU field:

ps waux | grep cron

root 105 97.3 1.1 236 340 ?? Is 9:11AM 137:14.29 cron

Here, cron is using 97% of the CPU time, and has accumulated over 2 hours of CPU time since this morning. It’s obviously sick, and we should put it out of its misery. To stop it, enter:

# kill 105

This command sends a signal called SIGTERM (terminate) to the process. This signal gives the process time to tidy up before exiting, so you should always try to use it first. The 105 is cron's PID, which we got from the ps command.

If the process doesn't go away with in a few seconds, it's probably ignoring SI GT ERM In this case, you can use the ultimate weapon:

# kill-9 105

The -9 is the number of SIGKILL a signal that cannot be caught or ignored. You can find a list of the signals and their numeric values in /usr/include/sys/signalh, which is part of the software development package.

FreeBSD also has a script called killall. As the name implies, it kills a group ol

G. Lehey FreeBSD Operating System

processes, by name. If you find that you have, say, a whole lot of runaway sendmail processes, and you might save the day by writing:

# killall sendmail

As we'll see else where, you can also use killall to send a signal to a single process when you know that only one is present. For example, to cause inetd to re-read its configuration file, you could write:

# killall-1 inetd

Timekeeping

FreeBSD is a networking system, so keeping the correct time is more important than on a standalone system Apart from the obvious problem of keeping the same time as other local systems, it's also important to keep time with systems in other time zones.

Internally, FreeBSD keeps the time as the number of seconds since the epoch, the beginning of recorded history: 00:00:00 UTC, 1 January 1970. UTC is the international base time zone, and means Universal Coordinated Time, despite the initials. It corresponds very closely, but not exactly, to Greenwich Mean Time (GMT), the local time in England in the winter. It would be inconvenient to keep all dates in UTC, so the system understands the concept of time zones. For example, in Walnut Creek, CA, the time zone in the winter is called PST (Pacific Standard Time), and in the summer it is PDT (Pacific Daylight Time) FreeBSD comes with a set of time zone description files in the directory hierarchy /usr/share/zoneinfo. We've already seen on page 95 that when you install the system, it stores information about the local time zone in the file /etc/localtime. Il you move time zones, you should change the time zone, not the time, either by running the tzsetup program, or simply by copying the file. For example, if you travel with a laptop from Adelaide, South Australia, to San Francisco CA, you would do:

# cp /usr/share/zoneinfo/America/Los_Angeles /etc/localtime

When you get home again, you would do:

# cp /usr/share/zoneinfo/Australia/Adelaide /etc/localtime

G. Lehey FreeBSD Operating System

At no time do you need to change the date or time directly.

Why Los_Angeles and not San_Francisco? The developers of the time zone package chose the largest city in the time zone. You need to have a certain understanding of the time zones to choose the correct one.

The TZ environment variable

An alternate means of describing the time zone is to set the environment variable T Z, which we looked at on page 128. You might use this form if you're connected to a remote system in a different time zone, or maybe just to find the time at some other place. For example, in Adelaide, SA I might find:

$ date

Sun Apr 14 13:31:15 CST2002

$ TZ=America/Los_Angeles date

Sat Apr 13 21:01:15 PDT 2002

Set the TZ variable to the name of the time zone info file in the /usr/share/zoneinfo hierarchy. For example, the value of TZ for Berlin, Germany is Europe/Berlin inFreeBSD.

This is not the same as the usage of the T Z variable in UNIX System V. System V doesn't have the time zone definition files in/usr/share/zoneinfo, so the TZ variable tells it information about the time zone. If you were using System V in Berlin, you would set your TZ variable to MEZIMSZ2, indicating time zone names and offsets fromUTC.

Keeping the correct time

If you're connected to the Internet on a reasonably regular basis, there are a number of programs which can help you synchronize your time via the ntp (Network Time Protocol) service.

A number of systems around the world supply time information via the ntp service. Look at httpy/www.eecis.udeLedu/~mills/ntp/servers.html to find one near you.

G. Lehey FreeBSD Operating System

Your choice of program depends on the nature of your connection to the Internet. If you're connected full time, you'll probably prefer ntpd, which keeps the system synchronized. Otherwise you can use ntpdate, which you can run as you feel like it.

ntpd

ntpd performs periodic queries to keep the system synchronized with a time server. There are many ways to run it—see the man page ntpd(8). In most cases, you can set up one system on the network to connect to an external time reference, and the other systems on the same Ethernet can get the time information from the first system

To get the time from an external source and broadcast it to the other systems on the network, create a file /etc/ntp.conf with a content like this:

server 227.21.37.18 this address is invalid; check what's near you driftfile /etc/ntp.drift

broadcast 223.147.37.255

The first line defines the server. The value in this example is invalid , so don't try to use it. It's important to get one near you: network delays can significantly impair the accuracy of the results, ntpd uses the file /etc/ntp.drift to record information about the (in) accuracy of the local system's clock. You only need the final line ii you have other systems on the network which wait for a broadcast message. It specifies the broadcast address for the network and also tells ntpd to broadcast on this address.

After setting up this file, you just need to start ntpd:

# ntpd

To ensure that ntpd gets started every time you reboot make sure that you have the following lines in /etc/rc.conf:

ntpd_enable='YES" # Run ntpd Network Time Protocol (or NO).

The comment on the first line is misleading: the value of ntpd_enable must be YES. You don't need any figs. You put exactly the same text in the /etc/rc.conf on

G. Lehey FreeBSD Operating System

the other machines, and simply omit the file /etc/ntp.conf. This causes ntpd on these machines to monitor broadcast messages.

In previous versions of FreeBSD, ntpd was called xntpd, so you may find things like xntpd_enable in your /etc/rc.conf. If you do, you'll have to change the name.

ntpdate

If you connect to the Internet infrequently, ntpd may become discouraged and not keep good time. In this case, it's better to use ntpdate. Simply run it when you want to set the time:

# ntpdate server

You can't use both ntpdate and ntpd at the same time: they both use the same port. Ntpd takes quite some time to synchronize, and if the time is wildly out, it won't even try, so it's often a good idea to run ntpdate on startup and then start ntpd manually.

Log files

Various components of FreeBSD report problems or items of interest as they happen. For example, there can always be problems with mail delivery, so a mail server should keep some kind of record of what it has been doing. If hardware problems occur, the kernel should report them. If somebody tries to break into the machine, the components affected should report the fact.

FreeBSD has a generalized system for logging such events. The syslogd daemon takes messages from multiple sources and writes them to multiple destinations, usually log files in the directory /var/log. You can change this behavior by modifying the file /etc/syslog.conf. See syslog.conf(5) for further details. In addition to syslogd, other programs write directly to files in this directory. The following files are of interest:

• • XFree86.0.1og contains the log file for the last (or current) X session started on display 0. This is a prime source of information if you run into problems withX.
• • auth.log contains information about user authentication. For example, you might see:

Dec 10 10:55:11 bumble su: grog to root on /dev/ttypO

Dec 10 12:00:19 bumble sshd[126]: Server listening on:: port 22.

Dec 10 12:00:19 bumble sshd[126]: Server listening on 0.0.0.0 port 22.

Dec 10 12:06:52 bumble sshd[167]: Accepted publickey for grog from 223.147.37.80 port 49564 ssh2

Dec 10 12:06:58 bumble su: BAD SU grog to root on /dev/ttypO

The first line is a successful su invocation; the last line is an unsuccessfill one (because the password was mistyped). The messages at 12:00:19 are from sshd startup, and the message at 12:06:52 is a successful remote login with ssh.

• cron is a log file for cron. It's relatively uninteresting:

Jan 5 16:00:00 bumble newsyslog[2668]: logfile turned over

Jan 5 16:05:00 bumble /usr/sbin/cron[2677]: (root) CMD (/usr/libexec/ai Jan 5 16:05:00 bumble /usr/sbin/cron[2678]: (root) CMD (/usr/libexec/ai Jan 5 16:10:00 bumble /usr/sbin/cron[2683]: (root) CMD (/usr/libexec/ai

If you have problems with cron, that could change rapidly.

• • dmesg.today and dmesg.yesterday are created by a cron job at 2 am every day. The dmesg message buffer wraps around, overwriting older entries, so they can be of use.
• • Lastlog is binary file recording last login information. You don't normally accesses it directly.
• • Maillog contains information about mail delivery.
• • message is the main log file.
• • The files mount.today and mount.yesterday show the currently mounted file systems in the format needed for /etc/fctab.
• • The file ppp.log contains information on PPP connections. We look at it on page 353.
• • The files setuid.today and setuid.yesterday contain a list of setuid files. The dafly security check compares them and sends a mail message if there are any differences.
• • The file vinumhistory contains information about vinum activity.
• • The file wtmp contains information about logins to the system. Like lasdog, it's in binary form. See utmp (5) for the format of both last log and wtmp.

A number of the more important log files are kept through several cycles. As the example above shows, cron runs the newsyslog command every hour new syslog checks the size of the files, and if they are larger than a certain size, it renames the old ones by giving them a numerical extension one higher than the current one, then renames the base file with an extension . 0 and compresses it. The result looks like this:

• -rw-r—r— 1
• -rw-r—r— 1
• -rw-r—r— 1
• -rw-r—r— 1
• -rw-r—r— 1
• -rw-r—r— 1
• -rw-r—r— 1

root wheel root wheel root wheel root wheel root wheel root wheel root wheel

• 31773 Jan 5 13:01 messages
• 8014 Jan 2 01:00 messages.O.bz2 10087 Dec 15 14:00 messages.I.bz2 9940 Dec 3 17:00 messages.2.bz2 9886 Nov 16 11:00 messages.3.bz2 9106 Nov 5 18:00 messages.4.bz2 9545 Oct 15 17:00 messages.5.bz2 newsyslog has a configuration file /etc/newsyslog.conf, which we discuss on page 572.

Multiple processor support

FreeBSD Release 5 can support most current Intel and AMD multiprocessor motherboards with the ia32 architecture. It also supports some Alpha, SPARC64 and Intel ia64 motherboards. Documentation on SMP support is currently rather scanty, but you can find some information at ññûëêà: http 'J/www. freebsd.Org/~fcmp/S MP/S MP.html

The GENERIC kernel does not support SMP, so you must build a new kerne] before you can use more than one processor. The configuration file /usr/src/sys/i386/conf/GENERIC contain the following commented-out entries:

# To make an SMP kernel, the next two are needed

#options SMP #Symmetric Multiprocessor Kernel

#options APIC_IO #Symmetric (APIC) I/O

For other platforms, you don't need APIC_IO. See Chapter 33 for information on how to build a new kernel

PC Card devices

As we have already seen, PC Card devices are special because they can be hot-plugged. They are also intended to be recognized automatically. Starting with Release 5, FreeBSD recognizes card insertion and removal in the kernel and invokes the appropriate driver to handle the event. When you insert a card you will see something like this on the system console:

ata2 at port 0x140-0x14f irq 11 function 0 config 1 on pccardO

ad4: 7MB [251/2/32] at ata2-master BIOS PIO

This is a compact fash memory card, which the system sees as an AJA disk. The kernel has created the necessary structures, but it can't know how to mount the device, for example. We'll look at what we can do about this in the next section.

devd: The device daemon

The device daemon, devd, provides a way to run user land programs when certain kernel events happen. It is intended to handle userland configuration of PC Card devices such as Ethernet cards, which it can do automatically. We'll look at this automatic usage on page 304.

devd reads the kernel event information from the device /dev/devctl and processes it according to rules specified in the configuration file /etc/devd.conf, which is installed with the system If you want to use it for other devices, you must modify /etc/devd.conf. This file contains a number of sections, referred to as statements in the man page:

• • The options statement describes file paths and a number of regular expressions (patterns) to look for in the messages it reads from /dev/devctl
• • attach statements specify what action to perform when a device is attached. For example:

attach 0 {

device-name "$scsi-controller-regex";

action "camcontrol rescan all";

};

The device-name entry uses the regular expression $scsi-controller-regex to recognize the name of a SCSI controller in

G. Lehey FreeBSD Operating System

the attach message. The action entry then specifies what action to take when such a device is attached to the system In this case, it runs the camcontrol program to rescan the SCSI buses and recognize any new devices that have been added.

Multiple attach statements can match a specific event, but only one will be executed. The order in which they are checked is specified by a priority, a numerical value after the keyword action . The statements are checked in order of highest to lowest numerical priority.

• detach statements have the same syntax as attach statements. As the name suggests, they are executed when a device is detached.

It's not always possible or necessary to perform any actions when a device is removed. In the case of SCSI cards, there is nodetach statement. We'll look at this issue in more detail below.

• Finally, if the kernel was unable to locate a driver for the card, it generates a no match event, which is handled by the nomatch statement.

So what does devd do when we insert the compact flash card? By default, nothing. The AIA driver recognizes and configures the card. It would be nice to get devd to mount it as well That's relatively simple:

• Ensure that you have an entry for the device in /etc/fstab. Digital cameras create a single MS-DOS file system on fash cards. An appropriate entry in /etc/fstab for this device might be:

/dev/ad4sl /camera msdos rw,noauto 0 0

This is a removable device, so you should use the no auto keyword to stop the system trying to mount it on system startup.

• In the options section of /etc/devd.conf add an expression to recognize the names of AIA controllers:

set ata-controller-regex

"ata[0-9]+";

• Add an attach section for the device: attach 0 {

device- name "$ata- controller-regex";

action "mount /camera";

};

• Restart devd:

# ê ilia 11 devd

# devd

After this, the file system will be automatically mounted when you insert the card.

Removing PC Card devices

The next thing we'd like to do is to unmount the file system when you remove the flash card. Unfortunately, that isn't possible. Unmounting can involve data transfer, so you have to do it before you remove the card. If you forget, and remove the card without unmounting, the system may panic next time you tty to access the card.

After unmounting, you can remove the card. On the console you'll see something like:

ad4: removed from configuration

ad4: no status, reselecting device

ad4: timeout sending command=e7 s=ff e=04

ad4: flushing cache on detach failed

ata2: detached

Alternate PC Card code

The PC Card implementation described here, called NEWCARD, is new in FreeBSD Release 5. At the time of writing, the older implementation, called OZDCARD, is still included in the system It's possible that you might have an older card that is supported by OLDCARD but not by NEWCARD. In that case, you will need to build a kernel with OLDCARD support. Check the NOTES files in /usr/src/sys/conf and /usr/src/sys/arch/conf, where arch is the architecture of

G. Lehey FreeBSD Operating System

your system, and the man pages pccard and pccard.conf.

Configuring PC Card devices at startup

A number of entries in /etc/rc.conf relate to the use of PC Card devices, but nearly all of them are for OLDC ARD. You only need one for NEWC ARD:

devd_enable="YES"

This starts devd at system startup.

Emulating other systems

A large number of operating systems run on Intel hardware, and there is a lot of software that is available for these other operating systems, but not for FreeBSD.

Emulators and simulators

There are a number of ways to execute software written for a different platform. The most popular are:

Simulation is a process where a program executes the functions that are normally performed by the native instruction set of another machine. They simulate the low-level instructions of the target machine, so simulators don't have to run on the same kind of machine as the code that they execute. A good example is the port emulators/pll, which simulates a PDP-11 minicomputer, the machine for which most early versions of UNIX were written.

• • Simulators run much more slowly than the native instruction set: for each simulated instruction, the simulator may execute hundreds of machine instructions. Amusingly, on most modern machines, the pll emulator still runs faster than the original PDP-11: modern machines are over 1,000 times faster than the PDP-11.
• • In general, emulators execute the program instructions directly and only simulate the operating system environment. As are suit, they have to run on the same kind of hardware, but they’re not noticeably slower than the

G. Lehey FreeBSD Operating System

original If there is any difference in performance, it's because of differences between the host operating system and the emulated operating system

• Another use for the term emulator is where the hardware understands a different instruction set than the native one. Obviously this is not the kind ol emulator we're talking about here.

FreeBSD can emulate many other systems to a point where applications written for these systems will run under FreeBSD. Most of the emulators are in the Ports Collection in the directory /usr/ports/emulators.

In a number of cases, the emulation support is in an experimental stage. Here's an overview:

• • FreeBSD will run most BSD/OS programs with no problems. You don't need an emulator.
• • FreeBSD will also run most NetBSD and OpenBSD executables, though not many people do this: it's safer to recompile them under FreeBSD.
• • FreeBSD runs Linux executables with the aid of the linux kid (loadable kernel module). We'll look at how to use it in the next section.
• • FreeBSD can run SCO COFF executables with the aid of the ibcs2 kid. This support is a little patchy: although the executables will run, you may run into problems caused by differences in the directory structure between SCO and FreeBSD. We'll look at it on page 164.
• • A Microsoft Windows emulator is available. We'll look at it on page 165.

Emulating Linux

Linux is a UNIX-like operating system that in many ways is very similar to FreeBSD. We discussed it on page 10. Although it looks very UNIX-like, many of the internal kernel interfaces are different from those of FreeBSD or other UNIX-based systems. The Linux compatibility package handles these differences, and most Linux software will run on FreeBSD. Most of the exceptions use specific drivers that don't run on FreeBSD, though there is a considerable effort to minimize even this category.

To install the Linux emulator, you must:

• Install the compatibility libraries. These are in the port

/usr/ports/emulators/lin-uxbase.

• Run the Linux emulator kid, linux.

Running the Linux emulator

Normally you load the Linux emulator when you boot the system. Put the following line in your /etc/rc.conf.

hnux_enable='YES"

If you don't want to do this for some reason, you can start it from the command line:

# kidload linux

You don't interact directly with the emulator module: it's just there to supply kernel functionality, so you get a new prompt immediately when you start it.

linux is a kid, so it doesn't show up in a p s listing. To check whether it is loaded, use

kidstat:

$ kidstat

Id Refs Address Size Name

• 1 5 OxcOlOOOOO ld08b0 kernel
• 2 2 0xcl20d000 aOOO ibcs2.ko
• 3 1 0xcl21b000 3000 ibcs2_coff.ko
• 5 1 Oxc1771000 eOOO linux.ko

This listing shows that the SCO UNIX emulation (ibcs2) has also been loaded.

The Linux emulator and many Linux programs are located in the directory hierarchy /usr/compat/linux. You won't normally need to access them directly, but if you get a Linux program that includes libraries destined for /lib, you will need to manually place them in /usr/compat/linux/lib. Be very careful not to replace any files in the /usr/lib hierarchy with Linux libraries; this would make it impossible to run FreeBSD programs that depend on them, and it's frequently very difficult to recover from such problems. Note that FreeBSD does not have a directory /lib,

G. Lehey

so the danger is relatively minor.

Linux pro cfs

Linux systems have a file system called procfs, or Process File System, which contains information used by many programs. FreeBSD also has a procfs, but it is completely different. To be able to run Linux programs which refer to procfs, place the following entry in your /etc/fstab file:

Linproc /compat/linux/proc linprocfs rw 0 0

Problems executing Linux binaries

One of the problems with the ELF format used by older Linux binaries is that they may contain no information to identify them as Linux binaries. They might equally well be BSD/OS or UnixWare binaries. That's normally not a problem, unless there are library conflicts: the system can't decide which shared library to use. Il you have this kind of binary, you must brand the executable using the program brandelf. For example, to brand the Star Office program swriter3, you would enter:

# brandelf -t Linux /usr/local/StarOffice-3.1/linux-x86/bin/swriter3

This example deliberately shows a very old version of Star Office: it's not clear that there are any modem binaries that cause such problems.

Emulating SCO UNIX

SCO UNIX, also known as SCO OpenDesktop and SCO Open Server, is based on UNIX System V3.2. This particular version of UNIX was current in the late 1980s. It uses an obsolete binary format called COFF (Common Object File Format).

Like Linux support, SCO support for FreeBSD is supplied as a loadable kernel module. It's not called sco, though: a number of older System V.3.2 systems, including Interactive UNIX, also support the ibcs2 ^standard. As a result, the kid

G. Lehey

is called ibcs2.

Run ibcs2 support like Linux support: start it manually, or modify /etc/rc. conf to start it automatically at boot up:

ibcs2_enable="YES" # Ibcs2 (SCO) emulation loaded at startup (or NO).

Alternatively, load the kid:

# kidload ibcs2

One problem with SCO emulation is the SCO shared libraries. These are required to execute many SCO executables, and they're not supplied with the emulator. They are supplied with SCO's operating systems. Check the SCO license to determine whether you are allowed to use them on FreeBSD. You may also be eligible for a free SCO license—see the SCO web site for further details.

Emulating Microsoft Windows

The wine project has been working for some time to provide an emulation of Microsoft's Windows range of execution environments. It's changing continually, so there's little point describing it here. You can find up-to-date information at httpy/www.winehq.com/about/, and you can install it from the port emulators/wine . Be prepared for a fair amount of work.

Accessing Microsoft files

Often you're not as interested in running Microsoft applications as decoding their proprietary formats. For example, you might get a mail message with an attachment described only as

[— Attachment #2: FreeBSD.doc

[— Type: application/octet-stream, Encoding: x-unknown, Size: 15K

[— application/octet-stream is unsupported (use V to view this part)

This attachment has an unspecific MIME type^, but you might guess that it is Microsoft Word format because the file name ends in .doc. That doesn’t make it any more legible. To read it, you need something that understands the format. A

G. Lehey FreeBSD Operating System

good choice is OpenOffice.org, a clone of Microsoft’s “Office” product. Install from the Ports Collection (/usr/ports/editors/openoffice).

OpenOffice.org is not a good example of the UNIX way. It breaks a number of conventions, and in general it's a lot more difficult to use than normal FreeBSD tools. Its only real advantage is that you can process Microsoft document formats.

ibcs2 stands for Intel Binary Compatibility System 2

²) See Chapter 26, Electronic mail: clients,page 489, for more information about MIME

How to install a package; Building a port; Package documentation; Getting binary-only software; Maintaining ports; Upgrading ports; Controlling installed ports; Submitting a new port;

The Internet is full of free software that is normally distributed in source form That can be a problem in it self the way from the source archive that you get free from the Internet to the finished, installed, running program on your machine—normally called porting, — can be a long and frustrating one. See my book Porting UNIX Software, for more details of the porting process.

To get a software package up and running on your system, you need to go through most of these steps:

• 1. Get the source files on your machine. They are usually contained in an archive, a file containing a number of other files. Archives used for the ports collection are generally gzipped tar, files, packaged with tar, and compressed with gzip, but other formats are also possible. What ever the format, you'll typically use ftp, to get them to your machine.
• 2. Unpack the archive source tree, in this case using gunzip, and tar,
• 3. Configure the package. Most packages include shell scripts to do this. Configuration performs a threefold adaptation of the package:
• 1. It adapts it to the system hardware.
• 2. It adapts it to the software environment you're running (in this case, FreeBSD).
• 3. It adapts it to your personal preferences.
• 4. Build the package. For most packages, this involves compiling the source files and creating executable. The main tool for this purpose is make, which uses a set of rules, traditionally stored in a file called Makefile, to decide how to build the package. There is nearly always a Makefile, in the sources, but the Ports Collection includes a second one that controls the build at a higher level
• 5. Install the package. This involves mainly copying the executable, configuration files and documentation created by a build to the correct place in the directory hierarchy.
• 6. Configure the installed software. This is similar in concept to package configuration, except that it occurs in the run-time environment. The package configuration may perform all the necessary configuration for you.

These are a lot of steps, and you'll often find they’re laid through a minefield: one false move and everything blows up. To make porting and installing software easier, the FreeBSD team created a framework called the Ports Collection, which makes it trivial to perform these steps. It also provides a method of packaging and installing the resultant ported software, called packages, The CD-ROM edition of FreeBSD includes a large number of pre-built packages that can be installed directly.

In this chapter, we'll consider the following points as they relate to the FreeBSD ports collection:

• • How to install a pre-compiled package. We'll look at this in the next section.
• • What the ports tree is, and how to compile and install ("build") a package. We'll look at this on page 169.
• • How to create and submit a new port, on page 174.

How to install a package

In FreeBSD parlance, a package is simply a special archive that contains those files (usually executable binary files) that are installed when you build and install a port. Effectively it's a snapshot of the port build process that we saw above, taken after step 4 has completed. Compared to the full-blown port, packages are much faster to install—it's usually a matter of seconds. On the other hand, they don't give you the choice of configuration that the complete port does. The distribution CD-ROMs contain a directory packages, with a large number of pre-compiled software packages. Alternatively, you can find FreeBSD packages on many servers on the Internet—check the online handbook for some places to look.

To help maintain an overview, both ports and packages are divided into categories. They are stored in directories named after the category. See the file /usr/ports/INDEX, for a list. For example, emacs, under editors, is currently in the file packages/editors/emacs-21.2.tgz, though this name will change with updated versions of emacs. For, the latest version of the packages only, you'll find another copy without the extension in packages/Latest/emacs.tgz. To install it, you enter:

pkg_add /cdrom/packages/Latest/emacs.tgz

Alternatively, you can install packages from the sysinstall, final configuration menu

G. Lehey FreeBSD Operating System

shown in Figure 6-1.

Building a port

The more general way to install third-party software is with a port, The FreeBSD project uses the term port to describe the additional files needed to adapt a package to build under FreeBSD. It does not include the source code itself, though the CD-ROM distribution includes many code archives in the directory /ports/distfiles, spread over several of the CD-ROMs.

Before you get started with the ports, you need to install the port information on your system. Normally this will be in /usr/ports. This directory tree is frequently called the Ports Tree. There are a number of ways to install them

Installing ports during system installation

The simplest way to install the Ports Collection is when you install the system. When you choose the components to install, sysinstall, offers to install the Ports Collection for you as welL

Installing ports from the first CD-ROM

The file ports/ports.tgz, on the first CD-ROM is a tar, archive containing all the ports. If you didn't install it during system installation, use the following method to install the complete collection (about 200 MB). Make sure your CD-ROM is mounted (in this example on /cdrom), and enter:

# cd/usr

# tar xzvf /cdrom/ports/ports.tgz

If you only want to extract a single package, say inn, which is in the categorynews, enter:

# cd/usr

# tar xzvf /cdrom/ports/ports.tgz ports/news/inn

It takes a surprisingly long time to install the ports; although there isn't much data in

G. Lehey FreeBSD Operating System

the archive, there are about 250,000 files in it, and creating that many files takes a lot of disk I/O.

Installing ports from the live file system CD-ROM

Alternatively, the files are also on the live file system CD-ROM. This is not much of an advantage for installation, but you may find it convenient to browse through the source trees in the directoiy ports, on the CD-ROM. Let's assume you have found a directoiy /cdram/ports/graphics/hp scan, on the CD-ROM, and it is your current working directory. You can move the data across with the following:

# cd/cdram/ports/graphics

# mkdir -p /usr/ports/graphics

# tar cf - . | (cd /usr/ports/graphics; tar xvf -)

Getting new ports

What happens when a new version of a port comes out? For example, you've been using Emacs Version 20 forever, and now Version 21.2 becomes available? It's brand new, so it's obviously not on your CD-ROM.

One way to get the port is via ftp. This used to be quite convenient: you could download a tar ball directly and extract it locally. That is unfortunately no longer possible: currendy you must download files a directoiy at a time. If you're following the Ports Collection at all closely, you should consider using cvsup, which can keep your sources up to date automatically. See Chapter 31, page 585, for more details.

AH ports are kept in subdirectories of the URL ññûëêà: ftp://ftp.FreeBSD.org/pub/FreeBSD/ports/. This directoiy has the following contents: drwxr-xr-x 6 1006 1006 512 Jun 8 13:18 alpha drwxr-xr-x 209 1006 1006 401408 May 28 14:08 dist files drwxr-xr-x 6 1006 1006 1536 May 28 17:53 i386 drwxr-xr-x 3 1006 1006 512 Apr 6 13:45 ia64 drwxr-xr-x 83 1006 1006 3072 May 20 15:35 local-dist files

G. Lehey

Irwxrwxrwx

Irwxrwxrwx

Irwxrwxrwx

Irwxrwxrwx

drwxr-xr-x

• 1 root wheel
• 1 root wheel
• 1 root wheel
• 1 root wheel
• 4 1006 1006

FreeBSD Operating System

• 13 Jun 1 2001 packages -> 1386/packages
• 24 Jun 1 2001 ports-../FreeBSD-current/pc
• 5 Jun 1 2001 ports-current -> ports
• 5 Jun 1 2001 ports-stable -> ports
• 512 Apr 9 10:37 sparc64

The directories alpha, i386, ia64, and sparc64, contain packages (not ports) for the corresponding architecture, dist files contains a large number of the original sources for the third-party packages; it's intended as a "last resort" location if you can't find them at other locations.

The directory local-dist files, is used by people working on the Ports Collection; you don't normally need anything from these directories. The important directories for you are ports, ports-current, and ports-stable. Currently these are realty all the same directory, but things may not remain like that.

Getting back to your emacs, port: you would find it in the directory /pub/Free-BSD/ports/ports/editors/. Note the final / in that directory name: if you leave it out, ftp prints an error message and exits. Here's what might happen:

$ ftp ftpÓ/ftp.FreeBSD.org/pub/FreeBSD/ports/ports/editors/

Connected to ftp.beastie.tdk.net.

• 220 ftp.beastie.tdk.net FTP server (Version 6.00LS) ready.
• 331 Guest login ok, send your email address as password.
• 230- The FreeBSD mirror at Tele Danmark Internet.

...much blurb omitted

• 250 CWD command successful
• 250 CWD command successful

ftp> Is

• 229 Entering Extended Passive Mode (|||55649|)
• 150 Opening ASCII mode data connection for '/bin/ls'.

total 704

G. Lehey FreeBSD Operating System

This shows that your files will be in the directory emacs21. You can get them with the ftp mget, command:

ftp> mget emacs21

mget emacs21/files [anpqy?]? a answer a for all files

Prompting off for duration of mget.

ftp: local: emacs21/files: No such file or directory

ftp: local: emacs21/Makefile: No such file or directory

(etc)

This happens because you need to create the destination directory manually. Try again:

ftp> !mkdir emacs21 create the local directory

ftp> mget emacs21

mget emacs21/files [anpqy?]? a

Prompting off for duration of mget.

• 229 Entering Extended Passive Mode (|||57074|)
• 550 emacs21/files: not a plain file.
• 229 Entering Extended Passive Mode (|||57085|)
• 150 Opening BINARY mode data connection for 'emacs21/Makefile' (2185 b) 2185 2 34 ]VH3/s ( 226 Transfer complete.
• (etc)

You get one of these for each file transferred. But note the error message: not a plain file. emacs21/files, is a directory, so we need to get it separately:

ftp> Imkdir emacs21/files

ftp> mget emacs21/files

mget emacs21/files/patch-lib-src:Makefile.in [anpqy?]? a

Prompting off for duration of mget.

• 229 Entering Extended Passive Mode (|||57258|)
• 150 Opening BINARY mode data connection for 'emacs21/files/patch-lib-src: W 100% |*************************************| 908 1 64 MB/s
• 226 Transfer complete.
• (etc)

Note that the ftp command specifies the URL of the directory. It must have a trailing /, otherwise ftp will complain. This form is supported by FreeBSD ftp but

G. Lehey FreeBSD Operating System

many other ftp clients will require you to do it in two steps:

# ftp ftp.EreeBSD.org

Connected to ftp.beastie.tdk.net.

(etc)

ftp> cd /pub/FreeBSD/ports/ports/editors

250 CWD command successful

What's in that port?

One problem with the Ports Collection is the sheer number. It can be difficult just to find out what they’re supposed to do. If you build all the ports, you'll be busy for weeks, and there's no way you could read all the documentation in one lifetime. Where can you get an overview? Here are some suggestions. In each case, you should have the directory /usr/ports, as your current working directory.

• There's an index in /usr/ports/INDEX. If you have updated the ports tree, you can make the index with the following commands:

# cd/usr/ports

# make index

index, is the name of a target, the part of a rule that identifies it. It's usually either a file name or an abbreviation for an operation to perform. We'll see a number of make, targets in the course of the book.

The index is intended for use by other programs, so it's written as a single long line per package, with fields delimited by the vertical bar character (|). Here are two lines as an example, wrapped over three lines to fit on the page:

mp3asm-0.1.3|/usr/ports/audio/mp3asm|/usr/local|MP3 frame level editor|/ s/audio/mp3asm/pkg-descr| Ýòîò àäðåñ e-mail çàùèùåí îò ñïàì-áîòîâ. ×òîáû óâèäåòü åãî, ó Âàñ äîëæåí áûòü âêëþ÷åí Java-Script |audio| autoconf213-2.1E htt py/mp3asm.sourceforge.net/ mp3blaster-3.0p8|/usr/ports/audio/mp3blaster|/usr/local|MP3 console ncu] dplayer|/usr/ports/audio/mp3blaster/pkg-descr| greid@ FreeBS D. org|audio http Ë www. stack.nl/~brama/mp3blaster. html

You'll probably want to process it with other tools.

• You can print the index with the following commands:

# cd/usr/ports

# make print-index | Ipr

Note that there are about 1,000 pages of output, which look like this:

Port: zip-2.3_1

Path: /usr/ports/archivers/zip

Info: Create/update ZIP files compatible with pkzip

Maint: Ýòîò àäðåñ e-mail çàùèùåí îò ñïàì-áîòîâ. ×òîáû óâèäåòü åãî, ó Âàñ äîëæåí áûòü âêëþ÷åí Java-Script

Index: archivers

B-deps: unzip-5.50

R-deps:

• You can search for a specific keyword with the search target. For example, to find ports related to Emacs, you might enter:

# cd/usr/ports

# make search key=Emacs | less

Pipe the output through less, it can be quite a lot.

• You can build a series of nearly 10,000 html, pages like this:

# cd/usr/ports

# make readmes

You can then browse them at the URL ññûëêà: file y//usr/ports/README.html

Getting the source archive

You'H see from the above example that there are not many files in the port. Most of the files required to build the software are in the original source code archive (the "tar ball"), but that's not part of the port.

There are a number of places from which you can get the sources. If you have a CD-ROM set, many of them are scattered over the CD-ROMs, in the directory /cdrom/ports/distfiles, on each CD-ROM. The Ports Collection Make files look for them in this directory (another good reason to mount your CD-ROM on /cdrom), and also in /usr/ports/distfiles.

If you don't have the source tar ball, that's not a problem. Part of the function of the Ports Collection is to go out on the Net and get them for you. This is completely automatic: you just type make, and the build process gets the source archive for you and builds it. Of course, you must be connected to the Internet for this to work.

If you mount your CD-ROM elsewhere (maybe because you have more than one CD-ROM drive, and so you have to mount the CD-ROM on, say, /cd4), the Make files will not find the distribution files and wifi try to load the files from the Internet. One way to solve this problem is to create a symbolic link from /cd4/ports/distfiles, to /usr/ports/distfiles. The trouble with this approach is that you will then no longer be able to load new distribution files into /usr/ports/distfiles, because it wiUbe on CD-ROM. Instead, do:

# cd/cd4/ports/distfiles

# mkdir -p /usr/ports/distfiles make sure you have a distfiles directory

# for i in *; do

> In -s /cd4/ports/distfiles/$i /usr/ports/distfiles/$i

> done

If you're using csh, or tcsh, enter:

# cd /cd4/ports/distfiles

# mkdir -p /usr/ports/distfiles make sure you have a distfiles directory

# foreach i (*)

• ? In -s /cd4/ports/distfiles/$i /usr/ports/distfiles/$i
• ? end

This creates a symbolic link to each distribution file, but if the file for a specific port isn't there, the Ports Collection can fetch it and store it in the directory.

Building the port

G. Lehey FreeBSD Operating System

Once you have the skeleton files for the port, the rest is simple. Just enter:

# cd /usr/ports/editors/emacs21

# make

# make install

====> To enable menubar fontset support, define WITH_MENUBAR_FONT5 » emacs-21.2.tar.gz doesn't seem to exist in/usr/ports/distfiles/.

» Attempting to fetch from ftp Ó/ftp.gnu.org/gnu/emacs/.

===> Extracting for emacs-21.2_1

» Checksum OK for emacs-21.2.tar.gz.

===> emacs-21.2_l depends on executable: gmake - found

===> emacs-21.2_l depends on executable: autoconf213 - not found

===> Verifying install for autoconf213 in /usr/ports/devel/autoconf213

===> Extracting for autoconf213-2.13.000227_2

» Checksum OK for autoconf-000227.tar.bz2.

===> autoconf213-2.13.000227_2 depends on executable: gm4 - not found

===> Verifying install for gm4 in /usr/ports/devel/m4

===> Extracting for m4-1.4_l

» Checksum OK for m4-1.4.tar.gz.

===> Patching for m4-1.4_l

===> Applying FreeBSD patches for m4-1.4_1

===> Configuring for m4-1.4_l

creating cache ./config.cache

checking for ma wk... no

(etc)

It's a good idea to perform the make, step first: make install, does not always build the package.

Port dependencies

Sometimes, it's not enough to build a single port. Many ports depend on other ports. If you have the complete, up-to-date ports tree installed on your systcode, the Ports Collection will take care of this for you: it will check if the other port is installed, and if it isn't, it will install it for you. For example, t kde s k, depends on tk, tk depends on tel. If you don't have any of them instated, and you try to build t kde s ê, it will recursively install t ê and t ñ 1 for you.

G. Lehey

Package documentation

Once you have installed your port, you'll want to use it. In almost every case, that requires documentation. Most packages have documentation, but unfortunately it's not always obvious where it is. In some cases, the port doesn't install all the documentation.

More generally, there are the following possibilities:

• If the port includes man pages, they will be installed in /usr/XHR6/man, if the package is related to X, and /usr/local/man, if they are not. Typically installing the man pages is the last thing that happens during the installation, so you should see it on the screen. If not, or if you want to check, you can have a look at the package list:

$ cd /var/db/pkg

$ pkgjnfo -L emacs-21.2_l|grep /man/

/usr/local/man/manl/ctags. 1 .gz

/usr/local/man/manl/emacs. 1 .gz

/usr/local/man/manl/etags. 1 .gz

/usr/locaVman/manl/gfdL 1 .gz

You don't need to change the directory to /var/db/pkg, but if you do, you can use file name completion to finish the name of the package. We use /man/ as the search string, and not simply man, because otherwise other files might match as well

• If the package includes GNU info pages, you can use the same method to look for them:

$ pkgjnfo -L emacs-21.2_l|grep /info/

/usr/local/info/ada-mode

/usr/local/info/autotype

/usr/local/info/ccmode

/usr/local/info/cl (many more)

This isn't normally necessary, though: if you're using GNU info, the index page will be updated to include the package.

• If the package includes hard copy documentation, it may or may not be included in the port. The Emacs, documentation also includes a user's guide and a programmer's guide. The user's guide, all 640 pages of it, is in the directory man of the Emacs build directory but it doesn't get built during installation. This is typical of most ports. In this case you'll have to build the documentation yourself.

Getting binary-only software

A lot of software doesn't need to be ported. For example, if you want Netscape , you can just download it from ññûëêà: ftpy/ftp.netscape.com. But how, do you install it? Netscape's installation procedures are getting better, but they still leave something to be desired.

The answer's simple: take the port! Although Netscape comes only in binary form, the port handles getting the correct version and installing it for you. Another advantage to using a port instead of installing the package manually is that the port installs the software as a FreeBSD package, which makes it much easier to remove the software later.

This method can be used to install some other software as weft for example Star Office. The moral is simple: always check the Ports Collection before getting a software package from the Net.

Maintaining ports

Once you install a port, you might consider that to be the end of the story. That's seldom the case. For example:

• • You might need to replace a port with a newer version. How do you do it? We'll look at that below.
• • One day, you might find your disk fills up, so you go looking for old ports you don't use anymore. We'll look at some utility commands on page 178.

Upgrading ports

From time to time, new versions of software will appear. There are a number of approaches to upgrading:

• • You can remove the old version of the port and install a new version. The trouble here is that removing the old version might remove any configuration files as well
• • You can install a new version without removing the old version. The trouble here is that you end up with two entries in the packages database /var/db/pkg:

$ pkgjnfo | grep emacs

emacs-21.1_5 GNU editing macros

emacs-21.2_l GNU editing macros

Clearly you don't need emacs-21.15 anymore. In fact, it's not complete anymore, because the program /usr/local/bin/emacs has been overwritten by the new version. But you can't remove it either: that would remove components of emacs-21.2_l, which you want to keep. On the other hand, if you don't remove it, you are left with nearly 50 MB of disk space used up in the directory /usr/local/share/emacs/21.1.

• You can use portupgrade, a program that does some of the upgrading automatically. We'll look at this below.

Using portupgrade

Portupgrade is—what else?—a port. Install it in the usual manner:

# cd /usr/ports/sysutils/portupgrade

# make install

Before you can perform the upgrade, you should first back up /var/db/pkg, then build a ports database with pkgdb. A typical build might look like this:

# cd /var/db

# tar czvf db.pkg.tar.gz pkg/

# pkgdb-F

[Updating the pkgdb in/var/db/pkg... - 181 packages found (-5 +92) (...)...............done]

Checking the origin of AbiWord-1.0.3

Checking the origin of ImageMagick-5.5.1.1

Checking the origin of ORBit-O.5.17

Checking the origin of xv-3.10a_3

Checking the origin of zip-2.3_l

Checking for origin duplicates

Checking AbiWord-1.0.3

Checking ImageMagick-5.5.1.1

Stale dependency: ImageMagick-5.5.1.1 -> ghostscript-gnu-7.05_3: ghostscript-gnu-6.52_4 (score:64%) ? ([y]es/[n]o/[a]ll) [no] ó

Fixed. (-> ghostscript-gnu-6.52_4)

Checking ORBit-O.5.17 Checking XFree86-4.2.0_l,l

Checking bonobo-1.0.21_1

Stale dependency: bonobo-1.0.21_1 -> ghostscript-gnu-7.05_3:

ghostscript-gnu-6.52_4 ? ([y]es/[n]o/[a]ll) [yes] Enter pressed

Fixed. (-> ghostscript-gnu-6.52_4)

Checking cdrtools-l.ll.a28

Checking xv-3.10a_3

Checking zip-2.3_1

Regenerating +REQUIREDJBY files

Checking for cyclic dependencies

In this example, the port ghostscript-gnu-7.05 3 had been replaced by the earlier version ghostscript-gnu-6.52_4, since ghostscript Release 7 has some annoying bugs. The dialogue shows how pkgdb, recognized the discrepancy, and how it recovered from it.

Now you can start the upgrade. To upgrade a specific port, simply specify its base name, without the version number. This example uses the -v, option to show additional information:

# portupgrade -v bison

• —> Upgrade of devel/bison started at: Mon, 04 Nov 2002 13:20:52 +1030
• —> Upgrading'bison-1.35_1' to 'bison-1.75' (devel/bison)
• —> Build of devel/bison started at: Mon, 04 Nov 2002 13:20:52 +1030

... normal port build output

===> Registering installation for bison-1.75

make clean issued by portupgrade

===> Cleaning for libiconv-1.8_2

===> Cleaning for gettext-0.11.5_l

• ---> Removing the temporary backup files
• —> Installation of devel/bison ended at: Mon, 04 Nov 2002 13:23:00 +1030 (c d00:00:06)
• —> Removing the obsoleted dependencies
• —> Cleaning out obsolete shared libraries
• —> Upgrade of devel/bison ended at: Mon, 04 Nov 2002 13:23:01 +1030 (coi 02:08)
• —> Reporting the results ( + succeeded / - ignored / * skipped / !:failed) +devel/bison (bison-1.35_1)

If the port is already up to date, you'll see something like this:

# portupgrade -v perl-5.8.0_3

** No need to upgrade 'perl-5.8.0_3' (>= perl-5.8.0_3). (specify -f to force) —> Reporting the results (+ succeeded / - ignored / * skipped / !:failed) -lang/per!5.8 (perl-5.8.0_3)

To upgrade all ports, use the command:

# portupgrade -a

Controlling installed ports

We've already seen the program pkg_add, when installing pre-compiled packages. There are a number of other pkg_ programs that can help you maintain installed ports, whether they have been instaked by pkg_add, or by make install from the Ports Collection:

• pkg_info, tells you which ports are installed. F or example:

$ pkgjnfo | less

AbiWord-1.0.3 An open-source, cross-platform WYSIWYG word { ImageMagick-5.5.1.1 Image processing tools (interactive optional—misc ORBit-O.5.17 High-performance CORBA ORB with support for the XFree86-4.2.0_l,l Xll/XFree86 core distribution (complete, using mi ... etc

bash-2.05b.004 The GNU Bourne Again Shell

bison-1.75 A parser generator from FSF, (mostly) compatible w

G. Lehey

bonobo-1.0.21_l cdrtooh-l.ll.a28 ... etc elm-2.4ME+22 elm-2.4ME+32

FreeBSD Operating System

The component and compound document system fo Cdrecord, mkisofs and several other programs to re

ELM Mail User Agent

ELM Mail User Agent

Note that the last two entries in this example show that two versions of elm, are installed. This can't be right; it happens when you install a new version without removing the old version and without running portupgrade. We'll discuss this matter further below.

• If you have the ports tree installed, you can use pkg_version, to check whether your ports are up to date. pkg_version, is a little cryptic in its output:

AbiWord-gnome =

ImageMagick <

ORBit <

Wingz =

XFree86 <

x2x-1.28 ?

The symbols to the right of the package names have the following meanings: = The installed version of the package is current.

< The installed version of the package is older than the current version.

The installed version of the package is newer than the current version.

> This situation can arise with an out-of-date index file, or when testing new ports.

• ? The installed package does not appear in the index. This could be due to an out of date index î repackage that has not yet been committed.
• * There are multiple versions of a particular software package listed in the index file.

The installed package exists in the index but for some reason,

! pkgversion, was unable to compare the version number of the installed package with the corresponding entry in the index.

• There are two ways to remove a port: if you've built it from source, and you're in the build directory you can write:

# make deinstall

Alternatively, you can remove any installed package with pkg_delete. For example, the list above shows two versions of the elm, mail user agent. To remove the older one, we enter:

# pkg_delete elm-2.4ME+22

File Vusr/local/man/manl/answer.r doesn't realty exist.

Unable to completely remove file 7usr/local/man/manl/answer.l'

File Vusr/local/man/manl/checkalias.l' doesn't realty exist.

Unable to completely remove file '/usr/local/man/manl/checkalias.l'

... etc

Couldn't entirety delete package (perhaps the packing list is incorrectly spt

In this case, it looks as if somebody has tried to remove the files before, so pkg_delete, couldn't do so.

Another problem with pkg_delete, is that it might delete files of the same name that have been replaced by newer packages. After performing this operation, we try:

$ elm

bash: elm: command not found

Oops! We tried to delete the old version, but we deleted at least part of the new version. Now we need to install it again.

The moral of this story is that things aren't as simple as they might be. When you install a new version of a package, you may want to test it before you commit to using it all the time. You can't just go and delete the old version. One possibility would be to install the new package, and try it out. When you've finished testing, delete both, packages and re-install the one you want to keep.

Keeping track of updates

The best way to find out about updates is to subscribe to the FreeBSD-ports mailing list. That way, you will get notification every time something changes. Il

G. Lehey FreeBSD Operating System

you're tracking the ports tree with CVSup, you also get the updates to the ports tree automatically. Otherwise you will have to download the port. In either case, to update your installed port, just repeat the build.

Submitting a new port

The Ports Collection is constandy growing. Hardly a day goes by without a new port being added to the list. Maybe you want to submit the next one? If you have something interesting that isn't already in the Ports Collection, you can find instructions on how to prepare the port in the FreeBSD Porter's Handbook. The latest version is available on the FreeBSD web site, but you'll also find it on your system as /usr/share/doc/en/porters-handbook/index.htmL

G. Lehey FreeBSD Operating System