Unix Tech Tips & Tricks

Small tutorial on SCCS

2007-06-05T00:31:00.001-07:00

Small tutorial on SCCS

The Basics

SCCS is a software versioning and revision control system. It works by maintaining information about files in a main directory (called SCCS). Each person working on the code creates a symbolic link to this directory in his/her own workspace. There is an SCCS directory for each project.

Setup

Decide on a central repository to store the code. This can be something like /usr/src/projectName.
Create the SCCS directory there: mkdir /usr/src/projectName/SCCS. Put the original files into the SCCS system using
sccs create filename
where filename is the name of the file.

Usage

Creating a file and putting it into sccs:
sccs create filename
checking files out for editing:
sccs edit filename
checking files in after editing:
sccs delget filename
getting a particular version of a file:
sccs get filename gets the latest version of the file
sccs get -rxx filename gets version xx of the file
getting the latest version of all files:
sccs get SCCS/s.*
getting information about which files are checked out:
sccs info
getting information about a particular file:
sccs prt filename
Diff between current file and checked in version:
sccs diffs filename

To modify a file, check it out for editing (edit), make the modifications, and then check it back in (delget).

Version info in the source code

SCCS provides the ability to mark your source files with the sccs information, such as the date of the last modification. To enable this, include the string %W% %G% in your source code. Generally this would be placed inside a comment. Once a file is checked in, the string gets replaced by the name of the file and the date of last modification.

Basic Source Control Using RCS

2007-06-04T22:14:00.001-07:00

Applying RCS and SCCS

From Source Control to Project Control

Basic Source Control Using RCS

The Revision Control System, or RCS, was developed by Walter F. Tichy at Purdue University in the early 1980s. Implemented later than SCCS, and with full knowledge of it, RCS is a more user-friendly system, and in most ways a more powerful one. In this chapter we present the most basic capabilities of RCS, by showing how you can apply it to the source file modification cycle.

Background

Traditionally, RCS has been included in BSD UNIX distributions; currently, it is also distributed by the Free Software Foundation [Egg91]. RCS has not traditionally been included in AT&T-derived UNIX distributions. Despite the technical merits of RCS, its absence from System V and earlier AT&T systems can present practical and political obstacles to those who would like to use it.

If RCS is of interest to you, make sure your system provides it. If not, you'll be obliged to obtain it from another source, such as the FSF. (We provide instructions for doing so in Appendix H, References.)[1] The FSF, of course, distributes RCS in source form only. Though it's normally trivial to configure and build RCS for a UNIX-like ("POSIX-compliant") platform, this is still something you would have to do yourself if you obtained the system in this way.

[1] A successor to RCS called RCE (for Revision Control Engine) has recently been announced by a group working in Germany with Walter Tichy [XCC95]. RCE is built atop a difference generator that works between arbitrary files, and is implemented as a library, permitting source control operations to be integrated with existing applications. A "stand-alone" command-line interface that is compatible with RCS is provided, as well as a graphical interface. We have not evaluated RCE; if it's of interest to you, see Appendix H for information on finding out more about it.

In this book we describe RCS version 5.6.0.1, the most recent one available as this book was being written.[2] This version of RCS contains the commands listed in Table 3.1.[3]

[2] Note that RCS 5.6.0.1 differs from 5.6 only in that it provides partial support for a new form of conflict output in doing three-way merges. (See Chapter 5, Extending Source Control to Multiple Releases, for a discussion of of such merges.) Since the new support is incomplete, it's disabled, making 5.6.0.1 effectively identical to 5.6. Version 5.7 of RCS was released just after this book went into production. Though it changes nothing fundamental, 5.7 does introduce a few new features. We flag the most important or visible of these in footnotes at the relevant points in our presentation. Appendix G, Changes in RCS Version 5.7, gives a more complete summary of what changed.

[3] We include in Table 3-1 the rcsclean(1) command, which in older RCS releases was a useful but limited shell script. In the current release, the command is implemented in C and uses much of the same internal code as the other RCS commands. Though the RCS sources still flag rcsclean as experimental, we think it's "grown up" enough to warrant inclusion as part of the standard system.

Table 3.1: The RCS Command Set

Command Description

ci Check in RCS revisions

co Check out RCS revisions

ident Identify files

merge Three-way file merge

rcs Change RCS file attributes

rcsclean Clean up working files

rcsdiff Compare RCS revisions

rcsmerge Merge RCS revisions

rlog Print log messages and other info on RCS files

Conventions

Before describing the basic RCS commands, let's define some terms and take a look at command-line conventions, especially how you specify files to the system.

Nomenclature

When RCS creates an archive file, the name of the archive file is the source file name with ,v appended to it. Thus if you created an archive for the file xform.c, xform.c,v would become the archive's name. The ",v" nominally refers to the multiple "versions" of the source file stored in the archive file. Naturally enough, RCS calls its archive files "RCS files."

All of the terms that we introduced in prior chapters to talk about source control in fact come from RCS. Thus RCS uses the term "revision" to refer to each stored version of the source file. It also uses the term "check-in" to refer to the addition of a new revision to an RCS file and "check-out" to refer to the retrieval of an existing revision from an RCS file. And a source file that's been retrieved from an RCS file is known as a "working file."

RCS Command Lines

Like most programs with a UNIX heritage, all RCS commands expect a command line that consists of a command name followed by one or more file names. The file names may be (but don't have to be) preceded by one or more options. If given, options change how the command works. So to summarize, a command line looks like

command-name [options] files

Each option begins with a hyphen, which is what distinguishes it from a filename. After the hyphen comes a single letter that identifies the option; then (for some options) comes a string that serves as a value for the option. Never insert whitespace between an option letter and its value--let them appear as one argument on the command line. (The first argument not starting with a hyphen is assumed to begin the filename arguments for the command.) Each file named on a command line can be either a source file or an RCS file, as we explain below.

Thus a typical command might be
% rcsdiff -r1.2 xform.c
This invocation of the rcsdiff(1) command specifies one option (-r, which has 1.2 as its value) and specifies one file, xform.c.

One final note is really not related to RCS, but to entering quoted strings on a shell command line. As we'll see, you sometimes have the choice of entering a description of an operation either at a prompt from the program you're running or directly on the program's command line. If you want to give the description on the command line, you'll need to enter it as a quoted string (because it will contain whitespace). And if you want to continue the description over more than one line, you'll have to use whatever convention your shell supports for continuing a command line.

For example, the -m option to the ci program specifies comments for a check-in operation. If you want to give a multiline comment and you're using csh(1) (or derivatives) as your shell, you need to precede each carriage return in the commentary with a backslash:
% ci -m"Fix CR 604: vary conditioning algorithm according to\
? range data supplied by caller." filter.sh
However, under the Bourne shell (or ksh(1) or bash(1)), as long as the value for -m is quoted, you don't need to do anything special to continue the comments onto a second line:
$ ci -m"Fix CR 604: vary conditioning algorithm according to
> range data supplied by caller." filter.sh
Naming Files

In running an RCS command, you can name either a working file or the corresponding RCS file on the command line; the command will automatically derive the other file name from the one you provide. This means, for instance, that these two command lines are equivalent:
% rcsdiff -r1.2 xform.c,v % rcsdiff -r1.2 xform.c
Another feature provided by RCS is the automatic use of an RCS subdirectory for RCS files. If you create such a subdirectory beneath the directory where you're working, RCS will try to use it before trying to use the current directory. RCS will not, however, create a subdirectory if one doesn't already exist.

Let's examine naming in more detail. Say that your working file has the name workfile and that path1 and path2 are UNIX pathnames. Then the full set of rules for specifying names to an RCS command looks like this:

If you name only a working file (such as, say, path1/workfile), the command tries to use an RCS file with the name path1/RCS/workfile,v or path1/workfile,v (in that order). Naturally, this is also what happens in the simple case in which path1 is not present.

If you name only an RCS file without a pathname prefix (such as workfile,v), the command tries to use workfile,v first in any RCS subdirectory beneath the current directory, then in the current directory itself. If it can use an RCS file with one of those names, it tries to use a working file named workfile in the current directory.

If you name an RCS file with a pathname prefix (such as path2/workfile,v), the command expects to be able to use an RCS file with exactly that name. Then it tries to use a working file named workfile in the current directory.

If you name both a working file and an RCS file, then the command uses files with exactly those names during its execution. In this case the two files can be specified in either order, and can come from completely unrelated directories.

Suppose, for instance, that in your current directory you had a source file xform.c, as well as an RCS subdirectory. Then any of these command lines would create an archive file named RCS/xform.c from the xform.c source file. (The command here is the "check-in" command we describe below.)
% ci xform.c
% ci xform.c,v
% ci RCS/xform.c,v
% ci RCS/xform.c,v xform.c
% ci xform.c RCS/xform.c,v
When the source file and the RCS file are in the same directory (or when the RCS file is in an RCS subdirectory), there's no need to give both file names on the command line. This becomes useful only if the two files are in unrelated directories. For example, if xform.c were in the directory /home/cullen/current/src/mathlib, but you wanted to create the RCS file in the directory /project/archive/mathlib, either of these command lines would do the trick:
% ci /home/cullen/current/src/mathlib/xform.c /project/archive/mathlib/xform.c,v
% ci /project/archive/mathlib/xform.c,v /home/cullen/current/src/mathlib/xform.c
Command lines like this one become useful when you put files into separate trees according to their type. (We mentioned this possibility at the end of Chapter 2, The Basics of Source Control.) This is one of the key concepts behind project control, as we'll see time and again in later chapters. If you take this approach, though, you won't want to be typing horrendously long command lines all the time. It's far better to create some kind of "tree mapper" to manage the filenames for you. Such a mapper is fundamental to systems like TCCS.

Naturally, for any RCS command, you can specify more than one file, and the command will process each file in turn. For your own sake, if you frequently process more than one file at a time, you'll probably want to use an RCS subdirectory to hold RCS files. This helps you avoid naming RCS files by mistake when you use wildcards to name groups of working files.

Note that RCS will take a command line of intermixed working filenames and RCS filenames and match them up using the rules we outlined earlier in this chapter. Though this may work all right for simple cases, however, the potential for ambiguity or erroneous file inclusion is great enough that you should avoid the situation altogether and just segregate your RCS files in an RCS subdirectory.

This is desirable for more general administrative reasons as well. Working files and RCS files are innately different, and it only makes sense to keep them in distinct places to make it easy to administer them appropriately. In particular, by segregating your RCS files, you make it harder to access them accidentally in any way other than through the RCS command set. An rm -rf will still remove them, of course, but the added safety of an RCS subdirectory shouldn't be neglected.

Basic RCS Commands

Now we present one iteration of the source file modification cycle, using RCS commands to implement each operation. We also cover a few other basic commands that are not strictly part of the cycle. All of this involves only some of the RCS commands and few (if any) of their many options. Later chapters explore more of the potential of the full RCS command set.

Figure 3.1 depicts the basic source control operations. This is the same picture we presented as Figure 2-1, but with the "bubbles" annotated to show which RCS command actually implements each operation. So once again, the central part of the figure shows the modification cycle.

Figure 3.1: Basic source control operations in RCS

Let's cover each of the operations in more depth. Roughly speaking, we'll describe them in the order in which they appear in the figure, working from top to bottom.

Creating an RCS File

You create an RCS file with the command ci(1) (for "check-in"). The command line need not specify anything but the name of the source file you're checking in. So a simple example of creating an RCS file is
% ci xform.c
which will create the file xform.c,v. If you've already made an RCS subdirectory, then the file will be created there. Otherwise, it will be created in the current directory.

By default, when you create an RCS file, you're prompted for a short description of the file you're putting under source control. You may enter as much text as you like in response, ending your input with a line containing a period by itself. The interaction looks like this:
% ci xform.c
xform.c,v  <--  xform.c initial revision: 1.1 enter description, terminated with ^D or '.': NOTE: This is NOT the log message! >> Matrix transform routines, for single-precision data.
>> .
done
Once the RCS file is created, your source file is immediately deleted. It is, of course, now safely stored in the RCS file and can be extracted as a working file whenever you want it.
As the warning "NOTE: This is NOT the log message!" implies, you really create two descriptions when you check in the initial revision of an archive file. The first description, which is what ci prompts for by default, is for the file itself--this message is meant to describe the role of the file in your project. In addition, ci also creates a log message (a term we'll come back to later), to describe the first revision of the archive file--you can use this description to trace the origins of the source file you're checking in.

By default, ci creates a log message with the value "Initial revision". If you want to use the message actually to capture some useful data, you can use the -m option on the ci command line to specify it, like this:
% ci -m"As ported from 9000 engineering group sources,\
? version 4.13." xform.c
Of course, this message has to be quoted, and the usual rules apply if it extends across multiple lines.

The ci command also lets you specify the archive file description on the command line, instead of being prompted for it, via the -t flag. In fact, you can use -t on any check-in, not just the first one, to change an archive's description. You can give a description either as the value to -t or in a file, which you name using -t.

If the value of the option starts with a hyphen, it's taken to be the literal text of the description; otherwise, it's taken to be the name of a file containing the description. So either of these command sequences would be equivalent to the original ci command we showed above:
% cat > xform.desc
Matrix transform routines, for single-precision data.
^D
% ci -txform.desc xform.c
% ci -t-"Matrix transform routines, for single-precision data." xform.c
Getting a Working File for Reading

You extract a working file from an existing RCS file with the command co (for "check-out"). The co(1) command is designed to be the mirror-image of ci(1). So, once again, in the simplest case you specify nothing but a filename when you run the command. A simple example of creating a working file is
% co xform.c
xform.c,v  -->  xform.c revision 1.1 done
This command will look for an RCS file with the name RCS/xform.c,v or xform.c,v and create a working file from it named xform.c. Here, the output from the command confirms that revision 1.1 of xform.c was extracted from the RCS file xform.c,v.

Since the command line doesn't explicitly say that you want to modify xform.c, the file is created read-only. This is a reminder that you shouldn't change it unless you coordinate your change with the RCS file (by locking the revision of xform.c that you want to modify).

If a writable file already exists with the same name as the working file that co is trying to create, the command will warn you of the file's presence and ask you whether you want to overwrite it. If a writable copy of xform.c existed, for instance, the exchange would look like this:
% co xform.c
RCS/xform.c,v  -->  xform.c revision 1.1 writable xform.c exists; remove it? [ny](n):
At this point, co expects a response from you that starts with y or n--responding with n, or with anything other than a word beginning with y, will cause co to abort the check-out. If you abort the check-out, co confirms that with the additional message
co error: checkout aborted
This message, of course, doesn't really indicate an "error"--just that the check-out was aborted as you requested.

CAUTION: As we said in Chapter 2, co will silently overwrite any read-only copy of a file that already exists with the same name as a working file it wants to check out, on the assumption that the existing file is the result of a previous co for reading. So if a file is under source control, do not try to maintain changed copies of it manually (i.e., outside source control). If you do, then sooner or later you're likely to delete a file you wanted to save.

You can change the way co checks out a file if for some reason the usual safeguards it provides against overwriting a working file aren't appropriate. First of all, you can use the -f option to "force" co to create a working file even if a writable file of the same name already exists. You might use -f if you had copied some outdated copy of the file into your work area but now wanted to overwrite it with a current copy from the archive file.

At the other extreme, you can check out a revision without affecting any file that already exists with the same name, by using the -p option. With -p, co will "print" the checked-out revision to its standard output, rather than putting it into a working file. You can then redirect standard output to capture the file in whatever way is appropriate. You might use -p if you wanted to have more than one revision of a file checked out simultaneously--you could check out all but one revision with -p into files with special names. (Of course, -p is purely a convenience. You can always avoid using it by doing regular check-outs and renaming the working files afterward.)

Getting a Working File for Modification

If you want to change a source file for which you've created an RCS file, you need to get a writable working copy by adding the -l option to the co command line. To check out xform.c for modification, you use the command line:
% co -l xform.c
xform.c,v  -->  xform.c revision 1.1 (locked) done
Compare the output from this command to that from the last co we looked at. As you can see, the current output confirms that a lock has been set on the revision of xform.c you've checked out. Now that you have the lock, you have the exclusive right to change this revision (revision 1.1) of the file and eventually to check in your working file as the next revision of the RCS file.

If someone else already held the lock to revision 1.1, you would not be able to lock it yourself. However, even when you can't lock a given revision, you can still check it out for reading only (that is, without the -l option). The assumption here is that you won't modify the file when you obtain it for reading only. If, for example, you requested the lock for revision 1.1 of xform.c but couldn't get it, co would inform you with an error message like this one:
% co -l xform.c
RCS/xform.c,v  -->  xform.c co error: revision 1.1 already locked by cullen
In this case you don't have the option of forcing the check-out to proceed, so co doesn't ask whether you want to. The check-out is aborted unconditionally. The error message points out what user owns the lock, which lets you contact him if you absolutely need to modify the file now. Perhaps he can check it back in. Even if he can't, waiting is better than circumventing RCS.

Occasionally, you may need to set a lock in an archive file without checking out a working file. Say, for instance, you're archiving sources distributed from outside your group, you've moved a new distribution into place, and now you want to check in the new version of each file. Checking out working files would overwrite the new sources with the older ones. To set a lock without creating a working file, use the command rcs -l.

Having a lock set in each archive file will enable you to check in the corresponding newly imported source file as a successor to the existing revision you locked.

Comparing a Working File to Its RCS File

To compare a working file against the RCS file it came from, use the rcsdiff(1) program. If, for instance, you want to compare the current contents of the working file against the original revision you checked out of the RCS file, just give the command with no options, as in
% rcsdiff xform.c
The rcsdiff command will output a line indicating what revision it is reading from the RCS file, then it will run the diff(1) program, comparing the revision it read against the current working file. The diff output will show the original revision as the "old" file being compared and the current working file as the "new" file being compared. Typical output might look like this:
% rcsdiff xform.c
=================================================================== RCS file: xform.c,v retrieving revision 1.1 diff -r1.1 xform.c 4a5 > j_coord = i_coord - x; 11,12c12,13 <       for (j = j_coord; j < j_max; ++j) <               if (a[j] < b[j]) { --- >       for (j = j_coord + 1; j <= j_max; ++j) >               if (a[j - 1] < b[j]) { 20d20 < j_coord = i_coord - x;
In other words, in the working file (the new file in the diff listing), an assignment to j_coord has moved from line 20 to line 4, and the first two lines of the for loop currently at line 12 have been changed.

You can also use rcsdiff to compare a working file against some revision other than the one it started from or to compare two different RCS file revisions to each other. To compare your working file against any revision of the RCS file, add a -r option to the rcsdiff command line, naming the revision you're interested in. For instance, to compare the current contents of xform.c against revision 1.3 of its RCS file, you use the command
% rcsdiff -r1.3 xform.c
To compare two different revisions already checked in to the RCS file, just give two -r options, as in
% rcsdiff -r1.1 -r1.2 xform.c
This command produces a diff listing with revision 1.1 as the "old" file and revision 1.2 as the "new" file. This form of rcsdiff can be particularly useful for debugging, since it lets you see recent changes to the file other than your own.

Adding a Working File to Its RCS File

When you're satisfied with the current state of your working file and want to save it for future reference, use the ci command to add it to the corresponding RCS file. This is, of course, the same command you used to create the RCS file in the first place; ordinarily, to check in a working file, you give the same simple command line as you did then. For instance,
% ci xform.c
This command would check in the current contents of xform.c as a new revision in the corresponding RCS file, then delete the working file. When you run ci, you'll be prompted for a description of your changes to the working file, in the same way as ci originally asked you to describe the file itself. A typical interaction might be
% ci xform.c
xform.c,v  <--  xform.c new revision: 1.2; previous revision: 1.1 enter log message: (terminate with ^D or single '.') >> In function ff1():  move declaration of j_coord; fix
>> off-by-one error in traversal loop.
>> .
done
Again, you can enter as much text as you like, and you terminate your entry with a period on a line by itself.

Sometimes, you may prefer to give revision commentary directly on the ci command line. This can be handy when you're checking in more than one file and want all of the files to have the same commentary. You do this using the -m option to ci (as we've mentioned a few times in other contexts). For instance, the last check-in that we showed could be phrased as
% ci -m"In function ff1():  move declaration of j_coord; fix\
? off-by-one error in traversal loop." xform.c
Notice that we gave the comments as a quoted string, as they contain white space. Since in this example we're using a csh(1)-style shell, we had to type a backslash to extend the comments onto a second line.

Ordinarily, ci expects a newly checked-in revision to be different from its ancestor and will not complete the check-in if the two are identical. You can use the -f option to "force" a check-in to complete anyway in this case. By default, ci deletes your working file when the check-in is complete. Often, you'll still want a copy of the file to exist afterward. To make ci do an immediate check-out of the working file after checking it in, you can add either of two options to the command line. The -u option will check out your working file unlocked, suitable for read-only use. The -l option will set a new lock on the revision that you just checked in and check out the working file for modification. Both of these options are simply shorthand for doing a separate co following the check-in.

Discarding a Working File

If you decide that you don't want to keep the changes that you've made, you can use the rcs(1) command to discard your changes by unlocking the RCS file revision you started with. Run rcs just by naming the file you want to discard, preceded by the option -u (for "unlock"):
% rcs -u xform.c
RCS file: xform.c,v 1.1 unlocked done
This command will remove any lock you currently have set in the RCS file. However, it doesn't do anything to the working file you name and doesn't even require that the file exist. If you want to remove the working file, you have to do that yourself with rm(1).

If you've set more than one lock in a file under the same username, you need to tell rcs the revision you wish to unlock, by adding a revision ID to the -u option. Without it, the command can't tell which pending update to the archive file you want to cancel. This command, for instance, would unlock revision 1.1 of xform.c,v even if you had another revision locked:
% rcs -u1.1 xform.c
RCS file: xform.c,v 1.1 unlocked done
If you want to discard a working file and replace it with the original revision it came from, it may be more convenient to use the command co -f -u. The -u option causes co to unlock the checked-out revision if it was locked by you, while -f forces co to overwrite your writable working file with the original revision from the archive file.

Viewing the History of an RCS File

As we've seen, the ci command asks you for a description when you create an RCS file, as well as when you add a revision to one. Together, these descriptions form a history, or log, of all that's happened to the RCS file since its creation. The descriptions can be displayed by using the rlog(1) command.

As usual, you simply give on the command line the name of the file you want to examine. Here's an example:
% rlog xform.c RCS file:        xform.c,v;   Working file:    xform.c head:            1.2 branch: locks:           ;  strict access list: symbolic names: comment leader:  " * " total revisions: 2;    selected revisions: 2 description: Matrix transform routines, for single-precision data. ---------------------------- revision 1.2 date: 95/05/10 14:34:02;  author: rully;  state: Exp;  lines added/del: 3/3 In function ff1():  move declaration of j_coord; fix off-by-one error in traversal loop. ---------------------------- revision 1.1 date: 95/04/23 14:32:31;  author: rully;  state: Exp; As ported from 9000 engineering group sources, version 4.13. =============================================================================
The output of rlog can be divided into three parts. First appears a summary of various characteristics of the RCS file, which is unrelated to what we've discussed in this chapter. Next, following the description: line, we find the text entered when the RCS file was first created. Last, a list of revision entries appears, one for each revision in the RCS file. These entries are output with the most recent first. Each one contains the description that was originally entered for that revision.

Cleaning Up an RCS Source Directory

To help you tidy up a source directory when you're done working there, RCS provides a program called rcsclean. This program compares working files in the current directory against their archive files and removes working files that were checked out but never modified. More specifically:

A working file that was checked out for reading is removed only if it still matches the head revision on the default branch of the archive file.[4]

[4] See Chapter 6, Applying RCS to Multiple Releases, for a discussion of RCS archive file branches.

If -u is given, a working file that was checked out for modification is removed if it still matches the original revision (that is, the one checked out locked by the user).

If a working file does not match the revision noted in the last two cases, then rcsclean will never remove it.

When -u is given, if rcsclean removes a working file, it also removes any lock corresponding to it. Any commands rcsclean executes are echoed to its standard output so you can see what's going on.

If you invoke rcsclean with no arguments, it will process all of the working files in the current directory. If you provide arguments, then only the working files you name will be processed. Needless to say, rcsclean has no effect on files other than working files checked out from an RCS file.

If you want to see what commands rcsclean would execute, if given a certain command line, you can use the -n flag. Then rcsclean will echo the commands it normally would run but will not actually execute them. Note that the output from rcsclean -n looks exactly like the normal output, so be careful not to confuse a -n run with the real McCoy.

Summary

You can put and keep files under source control with RCS by using only two commands, ci and co. This simplicity is a strong point of the system. We've also introduced the rcs command to abort a pending modification to an RCS file and informational commands rcsdiff and rlog, which give you detailed information about the contents of an RCS file. Finally, we presented rcsclean to remove unmodified working files.

Table 3.2 summarizes our presentation so far, by relating each operation in the source file modification cycle (plus a few other basic ones) to the RCS command that implements it.

Table 3.2: Basic RCS Commands

Command Basic Operation

ci Creating an archive file

co Getting a working file for reading

co -l Getting a working file for modification

rcsdiff Comparing a working file to its RCS file

ci Adding a working file to an RCS file

rcs -u plus rm Discarding a working file

rlog Viewing the history of an RCS file

rcsclean Cleaning up a source directory

Remember, too, that all of these commands employ an intelligent command-line interface that fairly well balances simplicity and flexibility and can provide an advantage over SCCS. That said, let's see what SCCS has to offer.

Table 3.1: The RCS Command Set
Command	Description
ci	Check in RCS revisions
co	Check out RCS revisions
ident	Identify files
merge	Three-way file merge
rcs	Change RCS file attributes
rcsclean	Clean up working files
rcsdiff	Compare RCS revisions
rcsmerge	Merge RCS revisions
rlog	Print log messages and other info on RCS files

Table 3.2: Basic RCS Commands
Command	Basic Operation
ci	Creating an archive file
co	Getting a working file for reading
co -l	Getting a working file for modification
rcsdiff	Comparing a working file to its RCS file
ci	Adding a working file to an RCS file
rcs -u plus rm	Discarding a working file
rlog	Viewing the history of an RCS file
rcsclean	Cleaning up a source directory

Understanding Virtual Memory -Linux

2007-04-02T02:28:00.001-07:00

Understanding Virtual Memory

by Norm Murray and Neil Horman

Introduction

One of the most important aspects of an operating system is the Virtual Memory Management system. Virtual Memory (VM) allows an operating system to perform many of its advanced functions, such as process isolation, file caching, and swapping. As such, it is imperative that an administrator understand the functions and tunable parameters of an operating system's Virtual Memory Manager so that optimal performance for a given workload may be achieved. After reading this article, the reader should have a rudimentary understanding of the data the Red Hat Enterprise Linux (RHEL3) VM controls and the algorithms it uses. Further, the reader should have a fairly good understanding of general Linux VM tuning techniques. It is important to note that Linux as an operating system has a proud legacy of overhaul. Items which no longer serve useful purposes or which have better implementations as technology advances are phased out. This implies that the tuning parameters described in this article may be out of date if you are using a newer or older kernel. Fear not however! With a well grounded understanding of the general mechanics of a VM, it is fairly easy to convert knowledge of VM tuning to another VM. The same general principles apply, and documentation for a given kernel (including its specific tunable parameters) can be found in the corresponding kernel source tree under the file Documentation/sysctl/vm.txt.

Definitions

To properly understand how a Virtual Memory Manager does its job, it helps to understand what components comprise a VM. While the low level view of a VM are overwhelming for most, a high level view is necessary to understand how a VM works and how it can be optimized for workloads.

What Comprises a VM

Figure 1. High Level Overview of VM Subsystem

The inner workings of the Linux virtual memory subsystem are quite complex, but it can be defined at a high level with the following components:

MMU

The Memory Management Unit (MMU) is the hardware base that makes a VM system possible. The MMU allows software to reference physical memory by aliased addresses, quite often more than one. It accomplishes this through the use of pages and page tables. The MMU uses a section of memory to translate virtual addresses into physical addresses via a series of table lookups.

Zoned Buddy Allocator

The Zoned Buddy Allocator is responsible for the management of page allocations to the entire system. This code manages lists of physically contiguous pages and maps them into the MMU page tables, so as to provide other kernel subsystems with valid physical address ranges when the kernel requests them (Physical to Virtual Address mapping is handled by a higher layer of the VM). The name Buddy Allocator is derived from the algorithm this subsystem uses to maintain it free page lists. All physical pages in RAM are cataloged by the Buddy Allocator and grouped into lists. Each list represents clusters of 2n pages, where n is incremented in each list. If no entries exist on the requested list, an entry from the next list up is broken into two separate clusters and is returned to the caller while the other is added to the next list down. When an allocation is returned to the buddy allocator, the reverse process happens. Note that the Buddy Allocator also manages memory zones, which define pools of memory which have different purposes. Currently there are three memory pools which the Buddy Allocator manages accesses for:

DMA — This zone consists of the first 16 MB of RAM, from which legacy devices allocate to perform direct memory operations.
NORMAL — This zone encompasses memory addresses from 16 MB to 1 GB and is used by the kernel for internal data structures as well as other system and user space allocations.
HIGHMEM — This zone includes all memory above 1 GB and is used exclusively for system allocations (file system buffers, user space allocations, etc).

Slab Allocator

The Slab Allocator provides a more usable front end to the Buddy Allocator for those sections of the kernel which require memory in sizes that are more flexible than the standard 4 KB page. The Slab Allocator allows other kernel components to create caches of memory objects of a given size. The Slab Allocator is responsible for placing as many of the cache's objects on a page as possible and monitoring which objects are free and which are allocated. When allocations are requested and no more are available, the Slab Allocator requests more pages from the Buddy Allocator to satisfy the request. This allows kernel components to use memory in a much simpler way. This way components which make use of many small portions of memory are not required to individually implement memory management code so that too many pages are not wasted. The Slab Allocator may only allocate from the DMA and NORMAL zones.

Kernel Threads

The last component in the VM subsystem are the kernel threads: kscand, kswapd, kupdated, and bdflush. These tasks are responsible for the recovery and management of in use memory. All pages of memory have an associated state (for more information on the memory state machine, refer to the section called “The Life of a Page” section. In general, the active tasks in the kernel related to VM usage are responsible for attempting to move pages out of RAM. Periodically they examine RAM, trying to identify and free inactive memory so that it can be put to other uses in the system.

The Life of a Page

All of the memory managed by the VM is labeled by a state. These states help let the VM know what to do with a given page under various circumstances. Dependent on the current needs of the system, the VM may transfer pages from one state to the next, according to the state machine in Figure 2. “VM Page State Machine”. Using these states, the VM can determine what is being done with a page by the system at a given time and what actions the VM may take on the page. The states that have particular meanings are as follows:

FREE — All pages available for allocation begin in this state. This indicates to the VM that the page is not being used for any purpose and is available for allocation.
ACTIVE — Pages which have been allocated from the Buddy Allocator enter this state. It indicates to the VM that the page has been allocated and is actively in use by the kernel or a user process.
INACTIVE DIRTY — This state indicates that the page has fallen into disuse by the entity which allocated it and thus is a candidate for removal from main memory. The kscand task periodically sweeps through all the pages in memory, taking note of the amount of time the page has been in memory since it was last accessed. If kscand finds that a page has been accessed since it last visited the page, it increments the page's age counter; otherwise, it decrements that counter. If kscand finds a page with its age counter at zero, it moves the page to the inactive dirty state. Pages in the inactive dirty state are kept in a list of pages to be laundered.
INACTIVE LAUNDERED — This is an interim state in which those pages which have been selected for removal from main memory enter while their contents are being moved to disk. Only pages which were in the inactive dirty state can enter this state. When the disk I/O operation is complete, the page is moved to the inactive clean state, where it may be deallocated or overwritten for another purpose. If, during the disk operation, the page is accessed, the page is moved back into the active state.
INACTIVE CLEAN — Pages in this state have been laundered. This means that the contents of the page are in sync with the backed up data on disk. Thus, they may be deallocated by the VM or overwritten for other purposes.

Figure 2. VM Page State Machine

Tuning the VM

Now that the picture of the VM mechanism is sufficiently illustrated, how is it adjusted to fit certain workloads? There are two methods for changing tunable parameters in the Linux VM. The first is the sysctl interface. The sysctl interface is a programming oriented interface, which allows software programs to modify various tunable parameters directly. It is exported to system administrators via the sysctl utility, which allows an administrator to specify a value for any of the tunable VM parameters via the command line. For example:

sysctl -w vm.max map count=65535

The sysctl utility also supports the use of a configuration file (/etc/sysctl.conf), in which all the desirable changes to a VM can be recorded for a system and restored after a restart of the operating system, making this access method suitable for long term changes to a system VM. The file is straightforward in its layout, using simple key-value pairs with comments for clarity. For example:

 #Adjust the min and max read-ahead for files vm.max-readahead=64 vm.min-readahead=32 #turn on memory over-commit  vm.overcommit_memory=2 #bump up the percentage of memory in use to activate bdflush vm.bdflush="40 500 0 0 500 3000 60 20 0"

The second method of modifying VM tunable parameters is via the proc file system. This method exports every group of VM tunables as a virtual file, accessible via all the common Linux utilities used for modifying file contents. The VM tunables are available in the directory /proc/sys/vm/ and are most commonly read and modified using the cat and echo commands. For example, use the command cat /proc/sys/vm/kswapd to view the current value of the kswapd tunable. The output should be similar to:

 512 32 8

Then, use the following command to modify the value of the tunable:

echo 511 31 7 > /proc/sys/vm/kswapd

Use the cat /proc/sys/vm/kswapd command again to verify that the value was modified. The output should be:

 511 31 7

The proc file system interface is a convenient method for making adjustments to the VM while attempting to isolate the peak performance of a system. For convenience, the following sections list the VM tunable parameters as the filenames they are exported to in the /proc/sys/vm/ directory. Unless otherwise noted, these tunables apply to the RHEL3 2.4.21-4 kernel.

bdflush

The bdflush file contains 9 parameters, of which 6 are tunable. These parameters affect the rate at which pages in the buffer cache (the subset of pagecache which stores files in memory) are freed and returned to disk. By adjusting the various values in this file, a system can be tuned to achieve better performance in environments where large amounts of file I/O are performed. Table 1. “bdflush Parameters” defines the parameters for bdflush in the order they appear in the file.

Parameter	Description
`nfract`	The percentage of dirty pages in the buffer cache required to activate the `bdflush` task
`ndirty`	The maximum number of dirty pages in the buffer cache to write to disk in each `bdflush` execution
`reserved1`	Reserved for future use
`reserved2`	Reserved for future
`interval`	The number of jiffies (10ms periods) to delay between `bdflush` iterations
`age_buffer`	The time for a normal buffer to age before it is considered for flushing back to disk
`nfract_sync`	The percentage of dirty pages in the buffer cache required to cause the tasks which are writing pages of memory to begin writing those pages to disk instead
`nfract_stop_bdflush`	The percentage of dirty pages in buffer cache required to allow `bdflush` to return to idle state
`reserved3`	Reserved for future use

Table 1. bdflush Parameters

Generally, systems that require more free memory for application allocation want to set the bdflush values higher (except for the age_buffer, which would be moved lower), so that file data is sent to disk more frequently and in greater volume, thus freeing up pages of RAM for application use. This, of course, comes at the expense of CPU cycles because the system processor spends more time moving data to disk and less time running applications. Conversely, systems which are required to perform large amounts of I/O would want to do the opposite to these values, allowing more RAM to be used to cache disk file so that file access is faster.

dcache_priority

This file controls the bias of the priority for caching directory contents. When the system is under stress, it selectively reduces the size of various file system caches in an effort to reclaim memory. By increasing this value, memory reclamation bias is shifted away from the dirent cache. By reducing this amount, the bias is shifted towards reclaiming dirent memory. This is not a particularly useful tuning parameter, but it can be helpful in maintaining the interactive response time on an otherwise heavily loaded system. If you experience intolerable delays in communicating with your system when it is busy performing other work, increasing this parameter may help.

hugetlb_pool

The hugetlb_pool file is responsible for recording the number of megabytes used for huge pages. Huge pages are just like regular pages in the VM, only they are an order of magnitude larger. Note also that huge pages are not swappable. Huge pages are both beneficial and detrimental to a system. They are helpful in that each huge page takes only one set of entries in the VM page tables, which allows for a higher degree of virtual address caching in the TLB (Translation Look-aside Buffer: A device which caches virtual address translations for faster lookups) and a requisite performance improvement. On the downside, they are very large and can be wasteful of memory resources for those applications which do not need large amounts of memory. Some applications, however, do require large amounts of memory and can make good use of huge pages if they are written to be aware of them. If a system is running applications which require large amounts of memory and is aware of this feature, then it is advantageous to increase this value to an amount satisfactory to that application or set of applications.

inactive_clean_percent

This control specifies the minimum percentage of pages in each page zone that must be in the clean or laundered state. If any zone drops below this threshold, and the system is under pressure for more memory, then that zone will begin having its inactive dirty pages laundered. Note that this control is only available on the 2.4.21-5EL kernels forward. Raising the value for the corresponding zone which is memory starved causes pages to be paged out more quickly, eliminating memory starvation at the expense of CPU clock cycles. Lowering this number allows more data to remain in RAM, increasing the system performance but at the risk of memory starvation.

kswapd

While this set of parameters previously defined how frequently and in what volume a system moved non-buffer cache pages to disk, in Red Hat Enterprise Linux 3, these controls are unused.

max_map_count

The max_map_count file allows for the restriction of the number of VMAs (Virtual Memory Areas) that a particular process can own. A Virtual Memory Area is a contiguous area of virtual address space. These areas are created during the life of the process when the program attempts to memory map a file, links to a shared memory segment, or allocates heap space. Tuning this value limits the amount of these VMAs that a process can own. Limiting the amount of VMAs a process can own can lead to problematic application behavior because the system will return out of memory errors when a process reaches its VMA limit but can free up lowmem for other kernel uses. If your system is running low on memory in the NORMAL zone, then lowering this value will help free up memory for kernel use.

max-readahead

The max-readahead tunable affects how early the Linux VFS (Virtual File System) fetches the next block of a file from memory. File readahead values are determined on a per file basis in the VFS and are adjusted based on the behavior of the application accessing the file. Anytime the current position being read in a file plus the current read ahead value results in the file pointer pointing to the next block in the file, that block is fetched from disk. By raising this value, the Linux kernel allows the readahead value to grow larger, resulting in more blocks being prefetched from disks which predictably access files in uniform linear fashion. This can result in performance improvements but can also result in excess (and often unnecessary) memory usage. Lowering this value has the opposite affect. By forcing readaheads to be less aggressive, memory may be conserved at a potential performance impact.

min-readahead

Like max-readahead, min-readahead places a floor on the readahead value. Raising this number forces a file's readahead value to be unconditionally higher, which can bring about performance improvements provided that all file access in the system is predictably linear from the start to the end of a file. This, of course, results in higher memory usage from the pagecache. Conversely, lowering this value, allows the kernel to conserve pagecache memory at a potential performance cost.

overcommit_memory

overcommit_memory is a value which sets the general kernel policy toward granting memory allocations. If the value is 0, then the kernel checks to determine if there is enough memory free to grant a memory request to a malloc call from an application. If there is enough memory, then the request is granted. Otherwise, it is denied and an error code is returned to the application. If the setting in this file is 1, the kernel allows all memory allocations, regardless of the current memory allocation state. If the value is set to 2, then the kernel grants allocations above the amount of physical RAM and swap in the system as defined by the overcommit_ratio value. Enabling this feature can be somewhat helpful in environments which allocate large amounts of memory expecting worst case scenarios but do not use it all.

overcommit_ratio

The overcommit_ratio tunable defines the amount by which the kernel overextends its memory resources in the event that overcommit_memory is set to the value of 2. The value in this file represents a percentage added to the amount of actual RAM in a system when considering whether to grant a particular memory request. For instance, if this value is set to 50, then the kernel would treat a system with 1 GB of RAM and 1 GB of swap as a system with 2.5 GB of allocatable memory when considering whether to grant a malloc request from an application. The general formula for this tunable is:

allocatable memory=(swap size + (RAM size * overcommit ratio))

Use these previous two parameters with caution. Enabling overcommit_memory can create significant performance gains at little cost but only if your applications are suited to its use. If your applications use all of the memory they allocate, memory overcommit can lead to short performance gains followed by long latencies as your applications are swapped out to disk frequently when they must compete for oversubscribed RAM. Also, ensure that you have at least enough swap space to cover the overallocation of RAM (meaning that your swap space should be at least big enough to handle the percentage if overcommit in addition to the regular 50 percent of RAM that is normally recommended).

pagecache

The pagecache file adjusts the amount of RAM which can be used by the page cache. The page cache holds various pieces of data, such as open files from disk, memory mapped files, and pages of executable programs. Modifying the values in this file dictates how much of memory is used for this purpose. Table 2. “pagecache Parameters” defines the parameters for pagecache in the order they appear in the file.

Parameter	Description
`min`	The minimum amount of memory to reserve for pagecache use.
`borrow`	The percentage of pagecache pages `kswapd` uses to balance the reclaiming of pagecache pages and process memory.
`max`	If more memory than this percentage is used by pagecache, `kswapd` only evicts pages from the pagecache. Once the amount of memory in pagecache is below this threshold, `kswapd` begins moving process pages to swap again.

Table 2. pagecache Parameters

Increasing these values allows more programs and cached files to stay in memory longer, thereby allowing applications to execute more quickly. On memory starved systems, however, this may lead to application delays as processes must wait for memory to become available. Moving these values downward swaps processes and other disk-backed data out more quickly, allowing for other processes to obtain memory more easily and increasing execution speed. For most workloads the automatic tuning is sufficient. However, if your workload suffers from excessive swapping and a large cache, you may want to reduce the values until the swapping problem goes away.

page-cluster

The kernel attempts to read multiple pages from disk on a page fault to avoid excessive seeks on the hard drive. This parameter defines the number of pages the kernel tries to read from memory during each page fault. The value is interpreted as 2^page-cluster pages for each page fault. A page fault is encountered every time a virtual memory address is accessed for which there is not yet a corresponding physical page assigned or for which the corresponding physical page has been swapped to disk. If the memory address has been requested in a valid way (for example, the application contains the address in its virtual memory map), then the kernel associates a page of RAM with the address or retrieves the page from disk and places it back in RAM. Then the kernel restarts the application from where it left off. By increasing the page-cluster value, pages subsequent to the requested page are also retrieved, meaning that if the workload of a particular system accesses data in RAM in a linear fashion, increasing this parameter can provide significant performance gains (much like the file readahead parameters described earlier). Of course if your workload accesses data discreetly in many separate areas of memory, then this can just as easily cause performance degradation.

Example Scenarios

Now that we have covered the details of kernel tuning, let us look at some example workloads and the various tuning parameters that may improve system performance.

File (IMAP, Web, etc.) Server

This workload is geared towards performing a large amount of I/O to and from the local disk, thus benefiting from an adjustment allowing more files to be maintained in RAM. This speeds up I/O by caching more files in RAM and eliminating the need to wait for disk I/O to complete. A simple change to sysctl.conf as follows usually benefits this workload:

 #increase the amount of RAM pagecache is allowed to use  #before we start moving it back to disk  vm.pagecache="10 40 100"

General Compute Server With Many Active Users

This workload is a very general type of configuration. It involves many active users who likely run many processes, all of which may or may not be CPU intensive or I/O intensive or a combination thereof. As the default VM configuration attempts to find a balance between I/O and process memory usage, it may be best to leave most configuration settings alone in this case. However, this environment likely contains many small processes which, regardless of workload, consume memory resources, particularly lowmem. It may help, therefore, to tune the VM to conserve low memory resources when possible:

 #lower the pagecache max to keep from eating all memory up with cache  vm.pagecache=10 25 50  #lower max-readahead to reduce the amount of unneeded IO  vm.max-readahead=16

Non interactive (Batch) Computing Server

A batch computing server is usually the exact opposite of a file server. Applications run without human interaction, and they commonly perform with little I/O. The number of processes running on controlled. Consequently this system should allow maximum throughput:

 #Reduce the amount of pagecache normally allowed vm.pagecache="1 10 100" #do not worry about conserving lowmem, not that many processes vm.max_map_count=128000 14 #crank up overcommit, processes can sleep as they are not interactive vm.overcommit=2  vm.overcommit_ratio=75

Cool Unix Commands

2007-03-07T01:35:00.001-08:00

Cool Commands

Peter Baer Galvin

There are so many commands in Solaris that it is difficult to separate the cool ones from the mundane. For example, there are commands to report how much time a program spends in each system call, and commands to dynamically show system activities, and most of these commands are included with Solaris 8 as well as Solaris 9. This month, Iâ€™m highlighting some of the commands that you might find particularly useful.

Systems administrators are tool users. Through experience, we have learned that the more tools we have, the better able we are to diagnose problems and implement solutions. The commands included in this column are gleaned from experience, friends, acquaintances, and from attendance at the SunNetwork 2002 conference in September. â€œThe /procodile Hunterâ€ talk by Solaris kernel developers Brian Cantrill and Mike Shapiro was especially enlightening and frightening because Cantrill wrote code to illustrate a point faster than Shapiro could explain the point they were trying to illustrate!

Useful Solaris Commands

truss -c (Solaris >= 8): This astounding option to truss provides a profile summary of the command being trussed:

$ truss -c grep asdf work.doc  syscall              seconds   calls  errors  _exit                    .00       1  read                     .01      24  open                     .00       8      4  close                    .00       5  brk                      .00      15  stat                     .00       1  fstat                    .00       4  execve                   .00       1  mmap                     .00      10  munmap                   .01       3  memcntl                  .00       2  llseek                   .00       1  open64                   .00       1                          ----     ---    ---  sys totals:              .02      76      4  usr time:                .00  elapsed:                 .05

It can also show profile data on a running process. In this case, the data shows what the process did between when truss was started and when truss execution was terminated with a control-c. Itâ€™s ideal for determining why a process is hung without having to wade through the pages of truss output.

truss -d and truss -D (Solaris >= 8): These truss options show the time associated with each system call being shown by truss and is excellent for finding performance problems in custom or commercial code. For example:

$ truss -d who  Base time stamp:  1035385727.3460  [ Wed Oct 23 11:08:47 EDT 2002 ]   0.0000 execve(â€œ/usr/bin/whoâ€, 0xFFBEFD5C, 0xFFBEFD64)  argc = 1   0.0032 stat(â€œ/usr/bin/whoâ€, 0xFFBEFA98)                = 0   0.0037 open(â€œ/var/ld/ld.configâ€, O_RDONLY)             Err#2 ENOENT   0.0042 open(â€œ/usr/local/lib/libc.so.1â€, O_RDONLY)      Err#2 ENOENT   0.0047 open(â€œ/usr/lib/libc.so.1â€, O_RDONLY)            = 3   0.0051 fstat(3, 0xFFBEF42C)                            = 0  . . .

truss -D is even more useful, showing the time delta between system calls:

Dilbert> truss -D who   0.0000 execve(â€œ/usr/bin/whoâ€, 0xFFBEFD5C, 0xFFBEFD64)  argc = 1   0.0028 stat(â€œ/usr/bin/whoâ€, 0xFFBEFA98)                = 0   0.0005 open(â€œ/var/ld/ld.configâ€, O_RDONLY)             Err#2 ENOENT   0.0006 open(â€œ/usr/local/lib/libc.so.1â€, O_RDONLY)      Err#2 ENOENT   0.0005 open(â€œ/usr/lib/libc.so.1â€, O_RDONLY)            = 3   0.0004 fstat(3, 0xFFBEF42C)                            = 0

In this example, the stat system call took a lot longer than the others.

truss -T: This is a great debugging help. It will stop a process at the execution of a specified system call. (â€œ-Uâ€ does the same, but with user-level function calls.) A core could then be taken for further analysis, or any of the /proc tools could be used to determine many aspects of the status of the process.

truss -l (improved in Solaris 9): Shows the thread number of each call in a multi-threaded processes. Solaris 9 truss -l finally makes it possible to watch the execution of a multi-threaded application.

Truss is truly a powerful tool. It can be used on core files to analyze what caused the problem, for example. It can also show details on user-level library calls (either system libraries or programmer libraries) via the â€œ-uâ€ option.

pkg-get: This is a nice tool (http://www.bolthole.com/solaris) for automatically getting freeware packages. It is configured via /etc/pkg-get.conf. Once itâ€™s up and running, execute pkg-get -a to get a list of available packages, and pkg-get -i to get and install a given package.

plimit (Solaris >= 8): This command displays and sets the per-process limits on a running process. This is handy if a long-running process is running up against a limit (for example, number of open files). Rather than using limit and restarting the command, plimit can modify the running process.

coreadm (Solaris >= 8): In the â€œoldâ€ days (before coreadm), core dumps were placed in the processâ€™s working directory. Core files would also overwrite each other. All this and more has been addressed by coreadm, a tool to manage core file creation. With it, you can specify whether to save cores, where cores should be stored, how many versions should be retained, and more. Settings can be retained between reboots by coreadm modifying /etc/coreadm.conf.

pgrep (Solaris >= 8): pgrep searches through /proc for processes matching the given criteria, and returns their process-ids. A great option is â€œ-nâ€, which returns the newest process that matches.

preap (Solaris >= 9): Reaps zombie processes. Any processes stuck in the â€œzâ€ state (as shown by ps), can be removed from the system with this command.

pargs (Solaris >= 9): Shows the arguments and environment variables of a process.

nohup -p (Solaris >= 9): The nohup command can be used to start a process, so that if the shell that started the process closes (i.e., the process gets a â€œSIGHUPâ€ signal), the process will keep running. This is useful for backgrounding a task that should continue running no matter what happens around it. But what happens if you start a process and later want to HUP-proof it? With Solaris 9, nohup -p takes a process-id and causes SIGHUP to be ignored.

prstat (Solaris >= 8): prstat is top and a lot more. Both commands provide a screenâ€™s worth of process and other information and update it frequently, for a nice window on system performance. prstat has much better accuracy than top. It also has some nice options. â€œ-aâ€ shows process and user information concurrently (sorted by CPU hog, by default). â€œ-câ€ causes it to act like vmstat (new reports printed below old ones). â€œ-Câ€ shows processes in a processor set. â€œ-jâ€ shows processes in a â€œprojectâ€. â€œ-Lâ€ shows per-thread information as well as per-process. â€œ-mâ€ and â€œ-vâ€ show quite a bit of per-process performance detail (including pages, traps, lock wait, and CPU wait). The output data can also be sorted by resident-set (real memory) size, virtual memory size, execute time, and so on. prstat is very useful on systems without top, and should probably be used instead of top because of its accuracy (and some sites care that it is a supported program).

trapstat (Solaris >= 9): trapstat joins lockstat and kstat as the most inscrutable commands on Solaris. Each shows gory details about the innards of the running operating system. Each is indispensable in solving strange happenings on a Solaris system. Best of all, their output is good to send along with bug reports, but further study can reveal useful information for general use as well.

vmstat -p (Solaris >= 8): Until this option became available, it was almost impossible (see the â€œse toolkitâ€) to determine what kind of memory demand was causing a system to page. vmstat -p is key because it not only shows whether your system is under memory stress (via the â€œsrâ€ column), it also shows whether that stress is from application code, application data, or I/O. â€œ-pâ€ can really help pinpoint the cause of any mysterious memory issues on Solaris.

pmap -x (Solaris >= 8, bugs fixed in Solaris >= 9): If the process with memory problems is known, and more details on its memory use are needed, check out pmap -x. The target process-id has its memory map fully explained, as in:

# pmap -x 1779  1779:   -ksh   Address  Kbytes     RSS    Anon  Locked Mode   Mapped File  00010000     192     192       -       - r-x--  ksh  00040000       8       8       8       - rwx--  ksh  00042000      32      32       8       - rwx--    [ heap ]  FF180000     680     664       -       - r-x--  libc.so.1  FF23A000      24      24       -       - rwx--  libc.so.1  FF240000       8       8       -       - rwx--  libc.so.1  FF280000     568     472       -       - r-x--  libnsl.so.1  FF31E000      32      32       -       - rwx--  libnsl.so.1  FF326000      32      24       -       - rwx--  libnsl.so.1  FF340000      16      16       -       - r-x--  libc_psr.so.1  FF350000      16      16       -       - r-x--  libmp.so.2  FF364000       8       8       -       - rwx--  libmp.so.2  FF380000      40      40       -       - r-x--  libsocket.so.1  FF39A000       8       8       -       - rwx--  libsocket.so.1  FF3A0000       8       8       -       - r-x--  libdl.so.1  FF3B0000       8       8       8       - rwx--    [ anon ]  FF3C0000     152     152       -       - r-x--  ld.so.1  FF3F6000       8       8       8       - rwx--  ld.so.1  FFBFE000       8       8       8       - rw---    [ stack ]  -------- ------- ------- ------- -------  total Kb    1848    1728      40       -

Here we see each chunk of memory, what it is being used for, how much space it is taking (virtual and real), and mode information.

df -h (Solaris >= 9): This command is popular on Linux, and just made its way into Solaris. df -h displays summary information about file systems in human-readable form:

$ df -h  Filesystem             size   used  avail capacity  Mounted on  /dev/dsk/c0t0d0s0      4.8G   1.7G   3.0G    37%    /  /proc                    0K     0K     0K     0%    /proc  mnttab                   0K     0K     0K     0%    /etc/mnttab  fd                       0K     0K     0K     0%    /dev/fd  swap                   848M    40K   848M     1%    /var/run  swap                   849M   1.0M   848M     1%    /tmp  /dev/dsk/c0t0d0s7       13G    78K    13G     1%    /export/home

Conclusion

Each administrator has a set of tools used daily, and another set of tools to help in a pinch. This column included a wide variety of commands and options that are lesser known, but can be very useful. Do you have favorite tools that have saved you in a bind? If so, please send them to me so I can expand my tool set as well. Alternately, send along any tools that you hate or that you feel are dangerous, which could also turn into a useful column!

HOWTO: Mirrored root disk on Solaris

2007-03-06T03:34:00.001-08:00

http://www.brandonhutchinson.com/Mirroring_disks_with_DiskSuite.html

0. Partition the first disk

# format c0t0d0

Use the partition tool (=> "p <enter>, p <enter>"!) to setup the slices. We assume the following slice setup afterwards:

#  Tag         Flag  Cylinders      Size      Blocks
 -  ----------  ----  -------------  --------  --------------------
 0  root        wm        0 -   812  400.15MB  (813/0/0)     819504
 1  swap        wu      813 -  1333  256.43MB  (521/0/0)     525168
 2  backup      wm        0 - 17659    8.49GB  (17660/0/0) 17801280
 3  unassigned  wm     1334 -  1354   10.34MB  (21/0/0)       21168
 4  var         wm     1355 -  8522    3.45GB  (7168/0/0)   7225344
 5  usr         wm     8523 - 14764    3.00GB  (6242/0/0)   6291936
 6  unassigned  wm    14765 - 16845    1.00GB  (2081/0/0)   2097648
 7  home        wm    16846 - 17659  400.15MB  (813/0/0)     819504

1. Copy the partition table of the first disk to its future mirror disk

# prtvtoc /dev/rdsk/c0t0d0s2  fmthard -s - /dev/rdsk/c0t1d0s2

2. Create at least two state database replicas on each disk

# metadb -a -f -c 2 c0t0d0s3 c0t1d0s3

Check the state of all replicas with metadb:

# metadb

Notes:

A state database replica contains configuration and state information about the meta devices. Make sure that always at least 50% of the replicas are active!

3. Create the root slice mirror and its first submirror

# metainit -f d10 1 1 c0t0d0s0
 # metainit -f d20 1 1 c0t1d0s0
 # metainit d30 -m d10

Run metaroot to prepare /etc/vfstab and /etc/system (do this only for the root slice!):

# metaroot d30

4. Create the swap slice mirror and its first submirror

# metainit -f d11 1 1 c0t0d0s1
 # metainit -f d21 1 1 c0t1d0s1
 # metainit d31 -m d11

5. Create the var slice mirror and its first submirror

# metainit -f d14 1 1 c0t0d0s4
 # metainit -f d24 1 1 c0t1d0s4
 # metainit d34 -m d14

6. Create the usr slice mirror and its first submirror

# metainit -f d15 1 1 c0t0d0s5
 # metainit -f d25 1 1 c0t1d0s5
 # metainit d35 -m d15

7. Create the unassigned slice mirror and its first submirror

# metainit -f d16 1 1 c0t0d0s6
 # metainit -f d26 1 1 c0t1d0s6
 # metainit d36 -m d16

8. Create the home slice mirror and its first submirror

# metainit -f d17 1 1 c0t0d0s7
 # metainit -f d27 1 1 c0t1d0s7
 # metainit d37 -m d17

9. Edit /etc/vfstab to mount all mirrors after boot, including mirrored swap

/etc/vfstab before changes:

fd                 -                   /dev/fd  fd     -  no   -
 /proc              -                   /proc    proc   -  no   -
 /dev/dsk/c0t0d0s1  -                   -        swap   -  no   -
 /dev/md/dsk/d30    /dev/md/rdsk/d30    /        ufs    1  no   logging
 /dev/dsk/c0t0d0s5  /dev/rdsk/c0t0d0s5  /usr     ufs    1  no   ro,logging
 /dev/dsk/c0t0d0s4  /dev/rdsk/c0t0d0s4  /var     ufs    1  no   nosuid,logging
 /dev/dsk/c0t0d0s7  /dev/rdsk/c0t0d0s7  /home    ufs    2  yes  nosuid,logging
 /dev/dsk/c0t0d0s6  /dev/rdsk/c0t0d0s6  /opt     ufs    2  yes  nosuid,logging
 swap               -                   /tmp     tmpfs  -  yes  -

/etc/vfstab after changes:

fd                 -                   /dev/fd  fd     -  no   -
 /proc              -                   /proc    proc   -  no   -
 /dev/md/dsk/d31    -                   -        swap   -  no   -
 /dev/md/dsk/d30    /dev/md/rdsk/d30    /        ufs    1  no   logging
 /dev/md/dsk/d35    /dev/md/rdsk/d35    /usr     ufs    1  no   ro,logging
 /dev/md/dsk/d34    /dev/md/rdsk/d34    /var     ufs    1  no   nosuid,logging
 /dev/md/dsk/d37    /dev/md/rdsk/d37    /home    ufs    2  yes  nosuid,logging
 /dev/md/dsk/d36    /dev/md/rdsk/d36    /opt     ufs    2  yes  nosuid,logging
 swap               -                   /tmp     tmpfs  -  yes  -

Notes:

The entry for the root device (/) has already been altered by the metaroot command we executed before.

10. Reboot the system

# lockfs -fa && init 6

11. Attach the second submirrors to all mirrors

# metattach d30 d20
 # metattach d31 d21
 # metattach d34 d24
 # metattach d35 d25
 # metattach d36 d26
 # metattach d37 d27

Notes:

This will finally cause the data from the boot disk to be synchronized with the mirror drive.

You can use metastat to track the mirroring progress.

12. Change the crash dump device to the swap metadevice

# dumpadm -d `swap -l  tail -1  awk '{print $1}'

13. Make the mirror disk bootable

# installboot /usr/platform/`uname -i`/lib/fs/ufs/bootblk /dev/rdsk/c0t1d0s0

Notes:

This will install a boot block to the second disk.

14. Determine the physical device path of the mirror disk

# ls -l /dev/dsk/c0t1d0s0
 ... /dev/dsk/c0t1d0s0 -> ../../devices/pci@1f,4000/scsi@3/sd@1,0:a

15. Create a device alias for the mirror disk

# eeprom "nvramrc=devalias mirror /pci@1f,4000/scsi@3/disk@1,0"
 # eeprom "use-nvramrc?=true"

Add the mirror device alias to the Open Boot parameter boot-device to prepare the case of a problem with the primary boot device.

# eeprom "boot-device=disk mirror cdrom net"

You can also configure the device alias and boot-device list from the Open Boot Prompt (OBP a.k.a. ok prompt):

ok nvalias mirror /pci@1f,4000/scsi@3/disk@1,0
 ok use-nvramrc?=true
 ok boot-device=disk mirror cdrom net

Notes:

From the OBP, you can use boot mirror to boot from the mirror disk.

On my test system, I had to replace sd@1,0:a with disk@1,0. Use devalias on the OBP prompt to determine the correct device path.

Active FTP vs. Passive FTP, a Definitive Explanation

2007-02-15T02:27:00.000-08:00

Active FTP vs. Passive FTP, a Definitive Explanation

http://slacksite.com/other/ftp.html

Introduction

One of the most commonly seen questions when dealing with firewalls and
other Internet connectivity issues is the difference between active and
passive FTP and how best to support either or both of them. Hopefully
the following text will help to clear up some of the confusion over how
to support FTP in a firewalled environment.

This may not be the definitive explanation, as the title claims,
however, I've heard enough good feedback and seen this document linked
in enough places to know that quite a few people have found it to be
useful. I am always looking for ways to improve things though, and if
you find something that is not quite clear or needs more explanation,
please let me know! Recent additions to this document include the
examples of both active and passive command line FTP sessions. These
session examples should help make things a bit clearer. They also
provide a nice picture into what goes on behind the scenes during an FTP
session. Now, on to the information...

The Basics

FTP is a TCP based service exclusively. There is no UDP component to
FTP. FTP is an unusual service in that it utilizes two ports, a 'data'
port and a 'command' port (also known as the control port).
Traditionally these are port 21 for the command port and port 20 for the
data port. The confusion begins however, when we find that depending on
the mode, the data port is not always on port 20.

Active FTP

In active mode FTP the client connects from a random unprivileged port
(N > 1023) to the FTP server's command port, port 21. Then, the client
starts listening to port N+1 and sends the FTP command PORT N+1 to the
FTP server. The server will then connect back to the client's specified
data port from its local data port, which is port 20.

>From the server-side firewall's standpoint, to support active mode FTP
the following communication channels need to be opened:

FTP server's port 21 from anywhere (Client initiates
connection)

FTP server's port 21 to ports > 1023 (Server responds to
client's control port)

FTP server's port 20 to ports > 1023 (Server initiates
data connection to client's data port)

FTP server's port 20 from ports > 1023 (Client sends
ACKs to server's data port)

When drawn out, the connection appears as follows:

<outbind://235/images/ftp/activeftp.gif>

In step 1, the client's command port contacts the server's command port
and sends the command PORT 1027. The server then sends an ACK back to
the client's command port in step 2. In step 3 the server initiates a
connection on its local data port to the data port the client specified
earlier. Finally, the client sends an ACK back as shown in step 4.

The main problem with active mode FTP actually falls on the client side.
The FTP client doesn't make the actual connection to the data port of
the server--it simply tells the server what port it is listening on and
the server connects back to the specified port on the client. From the
client side firewall this appears to be an outside system initiating a
connection to an internal client--something that is usually blocked.

Active FTP Example

Below is an actual example of an active FTP session. The only things
that have been changed are the server names, IP addresses, and user
names. In this example an FTP session is initiated from
testbox1.slacksite.com (192.168.150.80), a linux box running the
standard FTP command line client, to testbox2.slacksite.com
(192.168.150.90), a linux box running ProFTPd 1.2.2RC2. The debugging
(-d) flag is used with the FTP client to show what is going on behind
the scenes. Everything in red is the debugging output which shows the
actual FTP commands being sent to the server and the responses generated
from those commands. Normal server output is shown in black, and user
input is in bold.

There are a few interesting things to consider about this dialog. Notice
that when the PORT command is issued, it specifies a port on the client
(192.168.150.80) system, rather than the server. We will see the
opposite behavior when we use passive FTP. While we are on the subject,
a quick note about the format of the PORT command. As you can see in the
example below it is formatted as a series of six numbers separated by
commas. The first four octets are the IP address while the last two
octets comprise the port that will be used for the data connection. To
find the actual port multiply the fifth octet by 256 and then add the
sixth octet to the total. Thus in the example below the port number is (
(14*256) + 178), or 3762. A quick check with netstat should confirm this
information.

testbox1: {/home/p-t/slacker/public_html} % ftp -d testbox2
Connected to testbox2.slacksite.com.
220 testbox2.slacksite.com FTP server ready.
Name (testbox2:slacker): slacker
---> USER slacker
331 Password required for slacker.
Password: TmpPass
---> PASS XXXX
230 User slacker logged in.
---> SYST
215 UNIX Type: L8
Remote system type is UNIX.
Using binary mode to transfer files.
ftp> ls
ftp: setsockopt (ignored): Permission denied
---> PORT 192,168,150,80,14,178
200 PORT command successful.
---> LIST
150 Opening ASCII mode data connection for file list.
drwx------ 3 slacker users 104 Jul 27 01:45 public_html
226 Transfer complete.
ftp> quit
---> QUIT
221 Goodbye.

Passive FTP

In order to resolve the issue of the server initiating the connection to
the client a different method for FTP connections was developed. This
was known as passive mode, or PASV, after the command used by the client
to tell the server it is in passive mode.

In passive mode FTP the client initiates both connections to the server,
solving the problem of firewalls filtering the incoming data port
connection to the client from the server. When opening an FTP
connection, the client opens two random unprivileged ports locally (N >
1023 and N+1). The first port contacts the server on port 21, but
instead of then issuing a PORT command and allowing the server to
connect back to its data port, the client will issue the PASV command.
The result of this is that the server then opens a random unprivileged
port (P > 1023) and sends the PORT P command back to the client. The
client then initiates the connection from port N+1 to port P on the
server to transfer data.

>From the server-side firewall's standpoint, to support passive mode FTP
the following communication channels need to be opened:

FTP server's port 21 from anywhere (Client initiates
connection)

FTP server's port 21 to ports > 1023 (Server responds to
client's control port)

FTP server's ports > 1023 from anywhere (Client
initiates data connection to random port specified by server)

FTP server's ports > 1023 to remote ports > 1023 (Server
sends ACKs (and data) to client's data port)

When drawn, a passive mode FTP connection looks like this:

<outbind://235/images/ftp/passiveftp.gif>

In step 1, the client contacts the server on the command port and issues
the PASV command. The server then replies in step 2 with PORT 2024,
telling the client which port it is listening to for the data
connection. In step 3 the client then initiates the data connection from
its data port to the specified server data port. Finally, the server
sends back an ACK in step 4 to the client's data port.

While passive mode FTP solves many of the problems from the client side,
it opens up a whole range of problems on the server side. The biggest
issue is the need to allow any remote connection to high numbered ports
on the server. Fortunately, many FTP daemons, including the popular
WU-FTPD allow the administrator to specify a range of ports which the
FTP server will use. See Appendix 1 <outbind://235/ftp-appendix1.html>
for more information.

The second issue involves supporting and troubleshooting clients which
do (or do not) support passive mode. As an example, the command line FTP
utility provided with Solaris does not support passive mode,
necessitating a third-party FTP client, such as ncftp.

With the massive popularity of the World Wide Web, many people prefer to
use their web browser as an FTP client. Most browsers only support
passive mode when accessing ftp:// URLs. This can either be good or bad
depending on what the servers and firewalls are configured to support.

Passive FTP Example

Below is an actual example of a passive FTP session. The only things
that have been changed are the server names, IP addresses, and user
names. In this example an FTP session is initiated from
testbox1.slacksite.com (192.168.150.80), a linux box running the
standard FTP command line client, to testbox2.slacksite.com
(192.168.150.90), a linux box running ProFTPd 1.2.2RC2. The debugging
(-d) flag is used with the FTP client to show what is going on behind
the scenes. Everything in red is the debugging output which shows the
actual FTP commands being sent to the server and the responses generated
from those commands. Normal server output is shown in black, and user
input is in bold.

Notice the difference in the PORT command in this example as opposed to
the active FTP example. Here, we see a port being opened on the server
(192.168.150.90) system, rather than the client. See the discussion
about the format of the PORT command above, in the Active FTP Example
section <outbind://235/actexample> .

testbox1: {/home/p-t/slacker/public_html} % ftp -d testbox2
Connected to testbox2.slacksite.com.
220 testbox2.slacksite.com FTP server ready.
Name (testbox2:slacker): slacker
---> USER slacker
331 Password required for slacker.
Password: TmpPass
---> PASS XXXX
230 User slacker logged in.
---> SYST
215 UNIX Type: L8
Remote system type is UNIX.
Using binary mode to transfer files.
ftp> passive
Passive mode on.
ftp> ls
ftp: setsockopt (ignored): Permission denied
---> PASV
227 Entering Passive Mode (192,168,150,90,195,149).
---> LIST
150 Opening ASCII mode data connection for file list
drwx------ 3 slacker users 104 Jul 27 01:45 public_html
226 Transfer complete.
ftp> quit
---> QUIT
221 Goodbye.

Other Notes

A reader, Maarten Sjouw, pointed out that active FTP will not function
when used in conjunction with a client-side NAT (Network Address
Translation) device which is not smart enough to alter the IP address
info in FTP packets.

Summary

The following chart should help admins remember how each FTP mode works:

Active FTP :
command : client >1023 -> server 21
data : client >1023 <- server 20

Passive FTP :
command : client >1023 -> server 21
data : client >1023 -> server >1023

A quick summary of the pros and cons of active vs. passive FTP is also
in order:

Active FTP is beneficial to the FTP server admin, but detrimental to the
client side admin. The FTP server attempts to make connections to random
high ports on the client, which would almost certainly be blocked by a
firewall on the client side. Passive FTP is beneficial to the client,
but detrimental to the FTP server admin. The client will make both
connections to the server, but one of them will be to a random high
port, which would almost certainly be blocked by a firewall on the
server side.

Luckily, there is somewhat of a compromise. Since admins running FTP
servers will need to make their servers accessible to the greatest
number of clients, they will almost certainly need to support passive
FTP. The exposure of high level ports on the server can be minimized by
specifying a limited port range for the FTP server to use. Thus,
everything except for this range of ports can be firewalled on the
server side. While this doesn't eliminate all risk to the server, it
decreases it tremendously. See Appendix 1
<outbind://235/ftp-appendix1.html> for more information.

References

An excellent reference on how various internet protocols work and the
issues involved in firewalling them can be found in the O'Reilly and
Associates book, Building Internet Firewalls, 2nd Ed, by Brent Chapman
and Elizabeth Zwicky.

Finally, the definitive reference on FTP would be RFC 959, which sets
forth the official specifications of the FTP protocol. RFCs can be
downloaded from numerous locations, including
http://www.faqs.org/rfcs/rfc959.html.

Configuring TCP/IP on Solaris - Overview of the Booting Processes

2007-01-10T21:22:00.001-08:00

The Boot Process

The following information is provided for your reference. It is a brief overview of the network booting processes to help you better visualize what is happening during configuration.

Note - The names of startup scripts might change from one release to another.

You start the operating system on a host.

The kernel runs /sbin/init, as part of the booting process.

/sbin/init runs the /etc/rcS.d/S30rootusr.sh. startup script.

The script runs a number of system startup tasks, including establishing the minimum host and network configurations for diskless and dataless operations. /etc/rcS.d/S30rootusr.sh also mounts the /usr file system.

If the local database files contain the required configuration information (host name and IP address), the script uses it.

If the information is not available in local host configuration files, /etc/rcS.d/S30rootusr.sh uses RARP to acquire the host's IP address.

If the local files contain domain name, host name, and default router address, the machine uses them. If the configuration information is not in local files, then the system uses the Bootparams protocol to acquire the host name, domain name, and default router address. Note that the required information must be available on a network configuration server that is located on the same network as the host. This is necessary because no internetwork communications exist at this point.

After /etc/rcS/S30rootusr.sh completes its tasks and several other boot procedures have executed, /etc/rc2.d/S69inet runs. This script executes startup tasks that must be completed before the name services (NIS, NIS+, or DNS) can start. These tasks include configuring the IP routing and setting the domain name.

At completion of the S69inet tasks, /etc/rc2.d/S71rpc runs. This script starts the NIS, NIS+, or DNS name service.

After /etc/rc2.d/S71 runs, /etc/rc2.d/S72inetsvc runs. This script starts up services that depend on the presence of the name services. S72inetsvc also starts the daemon inetd, which manages user services such as telnet.

Configuring TCP/IP on Solaris - Network Configuration Procedures

2007-01-10T21:21:00.001-08:00

Introduction

Network software installation takes place along with the installation of the operating system software. At that time, certain IP configuration parameters must be stored in appropriate files so they can be read at boot time.

The procedure is simply a matter of creating or editing the network- configuration files. How configuration information is made available to a machine's kernel depends on whether these files are stored locally (local files mode) or acquired from the network configuration server (network client mode). Parameters supplied during network configuration are:

IP address of each network interface on every machine

Host names of each machine on the network. You can type the host name in a local file or a name service database.

NIS, NIS+, or DNS domain name in which the machine resides, if applicable

Default router addresses. You supply this only if you have a simple network topology with only one router attached to each network, or your routers donâ€™t run routing protocols such as the Router Discovery Server Protocol (RDISC) or the Router Information Protocol (RIP). (See Chapter 5 for more information about these protocols.)

Subnet mask (required only for networks with subnets)

This section contains complete information on creating and editing local configuration files.

How to Configure a Host for Local Files Mode

Use this procedure for configuring TCP/IP on a machine that run in local files mode.

Become superuser and change to the /etc directory.

Type the host name of the machine in the file /etc/nodename. For example, if the name of the host is tenere, type tenere in the file.

Create a file named /etc/hostname.interface for each network interface. (The Solaris installation program automatically creates this file for the primary network interface.)

Type either the interface IP address or the interface name in each /etc/hostname.interface file. For example, create a file named hostname.ie1, and type either the IP address of the host's interface or the host's name.

Edit the /etc/inet/hosts file to add:

IP addresses that you have assigned to any additional network interfaces in the local machine, along with the corresponding host name for each interface. The Solaris installation program will already have created entries for the primary network interface and loopback address.

IP address or addresses of the file server, if the /usr file system is NFS mounted.

Type the host's fully qualified domain name in the /etc/defaultdomain file. For example, suppose host tenere was part of the domain deserts.worldwide.com. Therefore, you would type: deserts.worldwide.com in /etc/defaultdomain.

Type the router's name in /etc/defaultrouter.

Type the name of the default router and its IP addresses in /etc/inet/hosts. Additional routing options are available. You can apply these options to a local files mode configuration.

If your network is subnetted, type the network number and the netmask in the file /etc/inet/netmasks. If you have set up a NIS or NIS+ server, you can type netmask information in the appropriate database on the server as long as server and clients are on the same network.

Reboot each machine on the network.

Setting Up a Network Configuration Server

If you plan to configure certain hosts as network clients, you must configure at least one machine on your network as a network configuration server. (Refer to â€œNetwork Configuration Serversâ€ on page 45 for an introduction.) Setting up a network configuration server involves:

Turning on the network configuration daemons:
- in.tftpd
- in.rarpd
- rpc.bootparamd

Editing and maintaining the network configuration files on the configuration server.

How to Set Up a Network Configuration Server

Become superuser and change to the root directory of the prospective network configuration server.

Turn on the in.tftpd daemon by creating the directory /tftpboot:

# mkdir /tftpboot

This configures the machine as a TFTP, bootparams, and RARP server.

Create a symbolic link to the directory.

# ln -s /tftpboot/. /tftpboot/tftpboot

Enable the tftp line in intetd.conf. Check that the /etc/inetd.conf entry reads:

tftp dgram udp wait root /usr/sbin/in.tftpd in.tftpd -s /tftpboot

This prevents inettftpd() from retrieving any file other than one located in /tftpboot.

Edit the hosts database, and add the host names and IP addresses for every client on the network.

Edit the ethers database, and create entries for every host on the network to run in network client mode.

Edit the bootparams database. Use the wildcard entry or create an entry for every host that run in network client mode.

Reboot the server.

Configuring Network Clients

Network clients receive their configuration information from network configuration servers. Therefore, before you configure a host as a network client you must ensure that at least one network configuration server is set up for the network.

How to Configure Hosts for Network Client Mode

Do the following on each host to be configured in network client mode:

Become superuser.

Check the directory for the existence of an /etc/nodename file. If one exists, delete it.

Eliminating /etc/nodename causes the system to use the hostconfig program to obtain the host name, domain name, and router addresses from the network configuration server.

Create the file /etc/hostname.interface, if it does not exist. Make sure that the file is empty. An empty /etc/hostname.interface file causes the system to acquire the IP address from the network configuration server.

Ensure that the /etc/inet/hosts file contains only the host name and IP address of the loopback network interface. The file should not contain the IP address and host name for the local machine (primary network interface). EXCEPTION: For a diskless client (a machine with an NFS-mounted root file system), type the name and IP address of the server that provides the client's root file system (usually, but not always, the network configuration server).

Check for the existence of an /etc/defaultdomain file. If one exists, delete it.

The hostconfig program sets the domain name automatically. If you want to override the domain name set by hostconfig, type the substitute domain name in the file /etc/defaultdomain.

Ensure that the search paths in the client's /etc/nsswitch.conf reflects the name service requirements for your network.

How to Specify a Router for the Network Client

If you have only one router on the network and you want the network configuration server to specify its name automatically, ensure that the network client does not have a /etc/defaultrouter file.

To override the name of the default router provided by the network configuration server:

Create /etc/defaultrouter on the network client.

Type the host name and IP address of the machine you have designated as the default router.

Add the host name and IP address of the designated default router to the network client's /etc/inet/hosts.

If you have multiple routers on the network, create /etc/defaultrouter on the network client, but leave it empty.

Creating /etc/defaultrouter and leaving it empty causes one of the two dynamic routing protocols to run: ICMP Router Discovery protocol (RDISC), or Routing Information Protocol (RIP). The system first runs the program in.rdisc, which looks for routers that are running the router discovery protocol. If it finds one such router, in.rdisc continues to run and keeps track of the routers that are running the RDISC protocol.

If the system discovers that routers are not responding to the RDISC protocol, it uses RIP and runs the daemon in.routed to keep track of them.

After Installing a Network Client

After you have finished editing the files on each network client machine, do the following on the network configuration server.

Add entries for the hosts in the ethers and hosts databases.

Add entries for the hosts to the bootparams database. To simplify matters, you can type a wild card in the bootparams database in place of individual entries for each host.

Reboot the server.

Configuring TCP/IP on Solaris - Network Databases and nsswitch.conf File

2007-01-10T21:20:00.001-08:00

Introduction

The network databases are files that provide information needed to configure the network. The network databases are:

hosts

netmasks

ethers

bootparams

protocols

services

networks

As part of the configuration process, you edit the hosts database and the netmasks database, if your network is subnetted. Two network databases, bootparams and ethers, are used to configure machines as network clients. The remaining databases are used by the operating system and seldom require editing.

Although it is not a network database, the nsswitch.conf file needs to be configured along with the relevant network databases. nsswitch.conf specifies which name service to use for a particular machine: NIS, NIS+, DNS, or local files.

How Name Services Affect Network Databases

Your network database takes a form that depends on the type of name service you select for your network. For example, the hosts database contains, at minimum, the host name and IP address of the local machine and any network interfaces directly connected to the local machine. However, the hosts database could contain other IP addresses and host names, depending on the type of name service on your network.

The network databases are used as follows:

Networks that use local files for their name service rely on files in the /etc/inet and /etc directories

NIS+ uses databases called NIS+ tables

NIS uses databases called NIS maps

DNS uses records with host information

Note - DNS boot and data files do not correspond directly to the network databases.

Network Database	Local Files	NIS+ Tables	NIS Maps
hosts	/etc/inet/hosts	hosts.ord_dir	hosts.byaddr hosts.byname
netmasks	/etc/inet/netmasks	netmasks.ord_dir	netmasks.byaddr
ethers	/etc/ethers	ethers.ord_dir	ethers.byname ethers.byaddr
bootparams	/etc/bootparams	bootparams.ord_dir	bootparams
protocols	/etc/inet/protocols	protocols.ord_dir	protocols.byname protocols.bynumber
services	/etc/inet/services	services.ord_dir	services.byname
networks	/etc/inet/networks	networks.ord_dir	networks.byaddr networks.byname

nsswitch.conf File - Specifying Which Name Service to Use

The /etc/nsswitch.conf file defines the search order of the network databases. The Solaris installation program creates a default /etc/nsswitch.conf file for the local machine, based on the name service you indicate during the installation process. If you selected the 'None' option, indicating local files for name service, the resulting nsswitch.conf file resembles the following example:

nsswitch.conf for Networks Using Files for Name Service

# /etc/nsswitch.files: # # An example file that could be copied over to /etc/nsswitch.conf; # it does not use any naming service. # # "hosts:" and "services:" in this file are used only if the # /etc/netconfig file contains "switch.so" as a # nametoaddr library for "inet" transports. passwd: files group: files hosts: files networks: files protocols: files rpc: files ethers: files netmasks: files bootparams: files publickey: files # At present there isn't a 'files' backend for netgroup; the # system will figure it out pretty quickly, # and won't use netgroups at all. netgroup: files automount: files aliases: files services: files sendmailvars: files

The nsswitch.conf(4) man page describes the file in detail. Its basic syntax is:

database name-service-to-search

The database field can list one of many types of databases searched by the operating system. For example, it could indicate a database affecting users, such as passwd or aliases, or a network database. The parameter name-service-to-search can have the values files, nis, or nis+ for the network databases. (The hosts database can also have dns as a name service to search.) You can also list more than one name service, such as nis+ and files.

In the above example, the only search option indicated is files. Therefore, the local machine gets security and automounting information, in addition to network database information, from files located in its /etc and /etc/inet directories.

Changing nsswitch.conf

The /etc directory contains the nsswitch.conf file created by the Solaris installation program. It also contains template files for the following name services:

nsswitch.files

nsswitch.nis

nsswitch.nis+

If you want to change from one name service to another, you can copy the appropriate template to nsswitch.conf. You can also selectively edit the nsswitch.conf file, and change the default name service to search for individual databases.

For example, on a network running NIS, you might have to change the nsswitch.conf file on diskless clients. The search path for the bootparams and ethers databases must list files as the first option, and nis. The example below shows the correct search paths.

nsswitch.conf for a Diskless Client on a Network Running NIS

## /etc/nsswitch.conf:# . . passwd: files nis group: file nis # consult /etc "files" only if nis is down. hosts: nis [NOTFOUND=return] files networks: nis [NOTFOUND=return] files protocols: nis [NOTFOUND=return] files rpc: nis [NOTFOUND=return] files ethers: files [NOTFOUND=return] nis netmasks: nis [NOTFOUND=return] files bootparams: files [NOTFOUND=return] nis publickey: nis netgroup: nis automount: files nis aliases: files nis # for efficient getservbyname() avoid nis services: files nis sendmailvars: files

bootparams Database

The bootparams database contains information used by diskless clients and machines configured to boot in the network client mode. You need to edit it if your network will have network clients. The database is built from information entered into the /etc/bootparams file.

The bootparams(4) man page contains complete syntax for this database. Its basic syntax is:

    machine-name file-key-server-name:pathname

For each diskless or network client machine, the entry might contain the following information: the name of the client, a list of keys, the names of servers, and path names.

The first item of each entry is the name of the client machine. Next is a list of keys, names of servers, and path names, separated by tab characters. All items but the first are optional. The database can contain a wildcard entry that will be matched by all clients. Here is an example:

bootparams Database

myclient root=myserver : /nfsroot/myclient \ swap=myserver : /nfsswap//myclient \ dump=myserver : /nfsdump/myclient

In this example the term dump=: tells diskless hosts not to look for a dump file.

Wildcard Entry for bootparams
In most cases, you will want to use the wildcard entry when editing the bootparams database to support diskless clients. This entry is:

    * root=server:/path dump=:

The asterisk (*) wildcard indicates that this entry applies to all clients not specifically named within the bootparams database.

ethers Database

The ethers database is built from information entered into the /etc/ethers file. It associates host names to their Ethernet addresses. You need to create an ethers database only if you are running the RARP daemon; that is, if you are configuring network clients or diskless machines.

RARP uses the file to map Ethernet addresses to IP addresses. If you are running the RARP daemon in.rarpd, you need to set up the ethers file and maintain it on all hosts running the daemon to reflect changes to the network.

The ethers(4) man page contains complete syntax information for this database. Its basic format is:

Ethernet-address hostname #comment Ethernet-address is the Ethernet address of the host. hostname is the official name of the host. #comment is any kind of note you want to append to an entry in the file.

The equipment manufacturer provides the Ethernet address. If a machine does not display the Ethernet address when you power up, see your hardware manuals for assistance.

When adding entries to the ethers database, make sure that host names correspond to the primary names in the hosts database, not to the nicknames, as shown in the following example:

Entries in the ethers Database

8:0:20:1:40:16 fayoum 8:0:20:1:40:15 nubian 8:0:20:1:40:7 sahara # This is a comment 8:0:20:1:40:14 tenere

Other Network Databases

The remaining network databases seldom need to be edited.

networks database Database

The networks database associates network names with network numbers, enabling some applications to use and display names rather than numbers. The networks database is based on information in the /etc/inet/networks file. It contains the names of all networks to which your network connects via routers.

The Solaris installation program sets up the initial networks database. The only time you need to update it is when you add a new network to your existing network topology.

The networks(4) man page contains full syntax information for /etc/inet/networks. Here is its basic format:

  network-name network-number nickname(s) # comment   network-name is the official name for the network.   network-number is the number assigned by the InterNIC.   nickname is any other name by which the network is known.   #comment is any kind of note you want to append to an entry in the file.

It is particularly important that you maintain the networks file. The netstat program uses the information in this database to produce status tables. The example shows a sample /etc/networks file:

/etc/networks File

#ident "@(#)networks 1.4 92/07/14 SMI" /* SVr4.0 1.1 */ # # The networks file associates Internet Protocol (IP) network numbers with network names. The format of this file is: # # network-name network-number nicnames . . . # The loopback network is used only for intra-machine communication #loopback 127 # Internet networks # arpanet 10 arpa # Historical ucb-ether 46 ucbether # # local networks eng 193.9.0 #engineering acc 193.9.1 #accounting prog 193.9.2 #programming

protocols Database

The protocols database lists the TCP/IP protocols installed on your system and their numbers; the Solaris installation program automatically creates it. It is rare when this file requires administrative handling.

The protocols database contains the names of the TCP/IP protocols installed on the system. Its syntax is completely described in the protocols(4) man page. The example below shows an example of the /etc/inet/protocols file:

/etc/inet/protocols File

# # Internet (IP) protocols # ip 0 IP # internet protocol, pseudo protocol number icmp 1 ICMP # internet control message protocol tcp 6 TCP # transmission control protocol udp 17 UDP # user datagram protocol

services Database

The services database lists the names of TCP and UDP services and their well known port numbers; it is used by programs that call network services. The Solaris installation automatically creates the services database; it generally requires no administrative handling.

The services(4) man page contains complete syntax information. The example below shows an excerpt from a typical /etc/inet/services file:

/etc/inet/services File

# # Network services # echo 7/udp echo 7/tcp discard 9/udp sink null discard 11/tcp daytime 13/udp daytime 13/tcp netstat 15/tcp ftp-data 20/tcp ftp 21/tcp telnet 23/tcp time 37/tcp timeserver time 37/udp timeserver name 42/udp nameserver whois 43/tcp nickname

Networking -- Solaris

2007-01-10T21:19:00.001-08:00

Introduction

In order to configure networking after installing Solaris, several files will need to be created and/or modified. This document provides a quick overview of those files along with example configuration data.

In most cases, the installation process performs all necessary configuration tasks. One of the tasks generally not performed by the installer is updating the Solaris networking files.

I have not found an easy way to force the installation program to configure all local networking files if the "Naming Services" section fails. For example, if you select the DNS naming service and the machine you are configuring is not entered in DNS, the installation process will skip this section. In cases like this, it will be necessary to update several of the files that pertain to networking. The following is a list of those files and the content that should be provided. Keep in mind that the system will need to be rebooted after making changes (and creating) these files.

/etc/resolv.conf

During the Solaris installation program, you are prompted for Naming Configuration information. In most cases, we use DNS. But during the installation process, if the installer is unable to communicate with and/or resolve your newly configured host with DNS, the Naming Configuration will fail, and none of the configuration files (i.e. /etc/resolv.conf) will not be updated. I often find it necessary to manually create the /etc/resolv.conf with any name service information.

nameserver 63.67.120.18 nameserver 63.67.120.23

/etc/resolv.conf

/etc/hostname.interface

The Solaris installation program creates this file for you. The file contains only one entry: the host name or IP address associated with the network interface. For example, suppose eri0 is the primary network interface for a machine called alexprod. Its /etc/hostname.interface file would have the name /etc/hostname.eri0; the file would contain the single entry alexprod.

alexprod

/etc/hostname.eri0

/etc/nodename

This file should contain one entry; the host name of the local machine. For example, on machine alexprod, the file /etc/nodename would contain the entry alexprod.

alexprod

/etc/nodename

/etc/defaultdomain

This file should contain one entry, the full qualified domain name of the administrative domain to which the local host's network belongs. You can supply this name to the Solaris installation program or edit the file at a later date.

Take for example the domain iDevelopment which was classified as a .info domain. In this example, /etc/defaultdomain should contain the entry iDevelopment.info.

idevelopment.info

/etc/defaultdomain

/etc/defaultrouter

This file should contain an entry for each router directly connected to the network. The entry should be the name for the network interface that functions as a router between networks.

If the default router for a machine will be 192.168.1.1, then this is the entry that should be put into the file /etc/defaultrouter.

192.168.1.1

/etc/defaultrouter

/etc/hosts

The hosts database contains the IP addresses and host names of machines on your network.

If you use local files for name service, the hosts database is maintained in the /etc/inet/hosts file. This file contains the host names and IP addresses of the primary network interface, other network interfaces attached to the machine, and any other network addresses that the machine must know about.

NOTE: For compatibility with BSD-based operating systems, the file /etc/hosts is a symbolic link to /etc/inet/hosts.

# # Internet host table # 127.0.0.1       localhost 192.168.1.102    alexprod alexprod.idevelopment.info    loghost

/etc/hosts

/etc/inet/netmasks

You need to edit the netmasks database as part of network configuration only if you have set up subnetting on your network. The netmasks database consists of a list of networks and their associated subnet masks.

# # The netmasks file associates Internet Protocol (IP) address # masks with IP network numbers. # #       network-number  netmask # # The term network-number refers to a number obtained from the Internet Network # Information Center.  Currently this number is restricted to being a class # A, B, or C network number.  In the future we should be able to support # arbitrary network numbers per the Classless Internet Domain Routing # guidelines. # # Both the network-number and the netmasks are specified in # "decimal dot" notation, e.g: # #               128.32.0.0 255.255.255.0 # 192.168.1.0      255.255.255.0

/etc/inet/netmasks

/etc/nsswitch.conf

The /etc/nsswitch.conf file defines the search order of the network databases (hosts, netmasks, ethers, bootparams, protocols, services, networks).

The Solaris installation program creates a default /etc/nsswitch.conf file for the local machine, based on the name service you indicate during the installation process. The installation process also creates 5 template files that can be copied over to /etc/nsswitch.conf:

nsswitch.files

nsswitch.nis

nsswitch.dns

nsswitch.ldap

nsswitch.nisplus

If you selected the 'None' option, indicating local files for name service, the resulting /etc/nsswitch.conf file resembles the following example:

# # /etc/nsswitch.files: # # An example file that could be copied over to /etc/nsswitch.conf; it # does not use any naming service. # # "hosts:" and "services:" in this file are used only if the # /etc/netconfig file has a "-" for nametoaddr_libs of "inet" transports.  passwd:     files group:      files hosts:      files ipnodes:    files networks:   files protocols:  files rpc:        files ethers:     files netmasks:   files bootparams: files publickey:  files # At present there isn't a 'files' backend for netgroup;  the system will #   figure it out pretty quickly, and won't use netgroups at all. netgroup:   files automount:  files aliases:    files services:   files sendmailvars:   files printers:       user files  auth_attr:  files prof_attr:  files project:    files

/etc/nsswitch.conf - Default if you are using local files

Here is another /etc/nsswitch.conf file that adds a dns entry for hosts::

# # /etc/nsswitch.dns: # # An example file that could be copied over to /etc/nsswitch.conf; it uses # DNS for hosts lookups, otherwise it does not use any other naming service. # # "hosts:" and "services:" in this file are used only if the # /etc/netconfig file has a "-" for nametoaddr_libs of "inet" transports.  passwd:     files group:      files  # You must also set up the /etc/resolv.conf file for DNS name # server lookup.  See resolv.conf(4). hosts:      files dns ipnodes:    files # Uncomment the following line and comment out the above to resolve # both IPv4 and IPv6 addresses from the ipnodes databases. Note that # IPv4 addresses are searched in all of the ipnodes databases before # searching the hosts databases. Before turning this option on, consult # the Network Administration Guide for more details on using IPv6. #ipnodes:   files dns  networks:   files protocols:  files rpc:        files ethers:     files netmasks:   files bootparams: files publickey:  files # At present there isn't a 'files' backend for netgroup;  the system will #   figure it out pretty quickly, and won't use netgroups at all. netgroup:   files automount:  files aliases:    files services:   files sendmailvars:   files printers:       user files  auth_attr:  files prof_attr:  files project:    files

/etc/nsswitch.conf - Adding a dns database for the hosts: element

Here is another /etc/nsswitch.conf file that uses a combination of files, nis, and dns entries:

# /etc/nsswitch.nis: # # An example file that could be copied over to /etc/nsswitch.conf; it # uses NIS (YP) in conjunction with files. # # "hosts:" and "services:" in this file are used only if the # /etc/netconfig file has a "-" for nametoaddr_libs of "inet" transports.  # the following two lines obviate the "+" entry in /etc/passwd and /etc/group. passwd:     files nis group:      files nis  # consult /etc "files" only if nis is down. hosts:      files dns nis ipnodes:    files # Uncomment the following line and comment out the above to resolve # both IPv4 and IPv6 addresses from the ipnodes databases. Note that # IPv4 addresses are searched in all of the ipnodes databases before # searching the hosts databases. Before turning this option on, consult # the Network Administration Guide for more details on using IPv6. #ipnodes:    nis [NOTFOUND=return] files  networks:   nis [NOTFOUND=return] files protocols:  nis [NOTFOUND=return] files rpc:        nis [NOTFOUND=return] files ethers:     nis [NOTFOUND=return] files netmasks:   nis [NOTFOUND=return] files bootparams: nis [NOTFOUND=return] files publickey:  nis [NOTFOUND=return] files  netgroup:   nis  automount:  files nis aliases:    files nis  # for efficient getservbyname() avoid nis services:   files nis sendmailvars:   files printers:       user files nis  auth_attr:  files nis prof_attr:  files nis project:    files nis

/etc/nsswitch.conf - Using a combination of files, nis, and dns databases

Removing Invalid Disk Device Files (/dev/dsk and /dev/rdsk)

2007-01-10T21:17:00.001-08:00

Removing Invalid Disk Device Files (/dev/dsk and /dev/rdsk)

by Jeff Hunter, Sr. Database Administrator

Overview

Whether installing a SCSI controller or even an additional IDE disk to a Sun Solaris machine, the Solaris O/S will:

Create Disk Device Files under the Hardware Device Tree (/devices).

Create symbolic links in /dev/dsk, /dev/rdsk, and /dev/cfg that point to the devices in the /devices directory.

Make entries in the /etc/path_to_inst file.

Things will generally work fine until you decide to remove or move a device in the system. I have had situations where I have run out of devices on a host because of Sun's poor ability to remove invalid (hanging) disk device files after removing a device. This is one area where Sun could really improve. It looks like they are trying new things with the boot -p option but I've only ever seen it remove things once.

There are other times when I simply wanted to replace a certain type of SCSI controller and wanted to reuse the controller ID's from a previously removed card. For example, I have a host (an E450) which had 2 internal controllers (0 and 1) and a dual differential SCSI card installed (controllers 2 and 3). I removed the dual differential SCSI host adapter and decided to replace it with a Single-Ended SCSI host adapter but Solaris would always assign them controller numbers 4 and 5. I wanted the system to reassign controller numbers 2 and 3 for the new host adapter but links still existed for the original dual differential SCSI host adapter.

My intention in this article is to provide several solutions for either renumbering disk device files (SCSI controllers, SCSI disks, IDE controllers, IDE disks, etc.) or simply removing old ones from replaced or removed devices. Please keep in mind that this article has been put together from notes I found during many searches for answers on the Internet. If anyone reading this has other solutions, please email me and I would be happy to post them for others going through this procedure.

Using the devfsadm Command

The devfsadm command was introduced with Solaris 7 and can be found in /usr/sbin/devfsadm. This command is used to maintain the /dev and /devices namespaces. The devfsadm command replaces the previous suite of devfs administration tools including drvconfig(1M), disks(1M), tapes(1M), ports(1M), audlinks(1M), and devlinks(1M). To maintain backwards compatibility, all previous devfs commands are hard links to devfsadm.

In many cases, you only need run the command:

  # devfsadm -C

to invoke the cleanup routines that are not normally invoked to remove dangling logical links.

Manual Methods

The devfsadm command was introduced with Solaris 7. For those running older versions of Solaris (i.e. Solaris 2.6) or simply want to perform all manual steps, this section describes the procedures to do just that.

Make a backup of your /etc/path_to_inst file and then modify the file so that all that exists is the SCSI / IDE reference for the boot drive. Remove all of the "pcipsy" and "glm" entries except for the one that is used by the controller that has the boot drive. Take note of the physical path of the controller you want to renumber.

Remove all /dev/dsk/cX* and /dev/rdsk/cX* files where X is the controller number(s) you want to remove and even those that no longer exist. (In the case of the example I provided on the E450, that would be 2, 3, 4, and 5.)

Remove all /dev/cfg/cX symbolic links where X is the controller(s) you want to remove. Make sure to not remove the controller with the boot drive. (Again, in the case of the example I provided on the E450, that would be 2, 3, 4, and 5.) It turns out this was one of the crucial steps that needed to be complete in order for Solaris to reuse controller numbers 2 and 3. The O/S was not able to reassign both of these controller numbers while the links (/dev/cfg/2 and /dev/cfg/3) still existed.

Remove all files under /devices/* for the controller you want to remove or renumber as indicated in Step #1.

Remove all files in /dev/sdXX* that symbolically link to controller(s) you do not want anymore. This may not be completely necessary, but it does clean things up.

Reboot the server with the "-srv" option:

ok boot -srv

Understanding Disk Device Files (i.e. breaking down c0t2d0s7)

2007-01-10T21:16:00.001-08:00

Understanding Disk Device Files (i.e. breaking down c0t2d0s7)

by Jeff Hunter, Sr. Database Administrator

Overview

Under Solaris, one of the most involved UNIX devices to understand is the disk device file. Here are several key points that may help:

In many cases, a disk device file (i.e. /dev/dsk/c0t2d0s7) refers to a particular partition (aka "slice") of a disk, and not the entire physical device. There are several device files which refer to the entire physical device, but are rarely used.

For every disk device, there are usually two device files - the block device and the character ("raw") device. In general:

block devices are generally stored under /dev/dsk and used for filesystem type access (e.g mount)

character devices are generally stored under /dev/rdsk used for everything else (e.g. fsck, newfs, etc..)

Discs are generally attached to a controller (or a bus) which can handle multiple devices. IDE and SCSI are both common attach methods. This tends to make disk device filename more complex than other types of devices.

/etc/vfstab

To see the difference between the block device and character device for a device, consider the following. The /etc/vfstab contains entries for a single filesystem on a Solaris server:

/dev/dsk/c0t2d0s7 /dev/rdsk/c0t2d0s7 /opt ufs 3 yes -

The first 2 fields in the above entry, list the same disk device as both a block device ("dsk") and character device ("rdsk"). The block device is used by mount when mounting the filesystem while the character device is used by fsck when checking the filesystem and newfs when creating the filesystem.. Both fields must be present in /etc/vfstab.

Breaking Down c0t2d0s7

This section breaks down the different components of a disk device file. In this example, I will be using the disk device file: c0t2d0s7. The four components of the disk device file are: controller, target, LUN and slice/partition and further defined in the following table:

`c0`	This device is attached to controller #0. On a SPARCstation this is usually the on-board SCSI or IDE controller. If this is a PC it usually refers to the first IDE controller on the motherboard.
`t2`	The device is target #2 - (i.e. the second device on this controller.) On a SCSI controller this is the SCSI target ID and is usually set via a switch on any external enclosure or by jumpers on the disk itself. On an IDE controller target #2 refers to the second IDE disk. With IDE this is generally determined by the device's position on the IDE cable.
`d0`	The device is Logical Unit / "LUN" #0 (the first) on this target. Under SCSI a single target can support up-to eight devices. This is rarely seen in practice, but some hardware raid controllers use LUNs.
`s7`	Slice or Partition number 7. Under Solaris, this relates to the partition number as set when using the `format` command.

Adding SCSI Host Adapter (X6541A) into a Blade 100/150

2007-01-10T21:10:00.001-08:00

Adding SCSI Host Adapter (X6541A) into a Blade 100/150

by Jeff Hunter, Sr. Database Administrator

Overview

A Sun Blade 100/150 can accept the following PCI SCSI host adapters:

Option #	Top Level Part #	Manufacturing Part #	Description	Substitute Part #
X1032A	595-4258	501-5656	Single-Ended Ultra/Wide SCSI/FastEthernet (SunSwift PCI)	501-2741
X2222A	595-5624	501-5727	Dual Ultra-2 SCSI/Dual FastEthernet PCI Adapter	n/a
X5010A	595-5377	375-0097	Single-Channel Single-Ended Ultra/Wide SCSI (PCI)	n/a
X6540A	595-4399	375-0005	Dual Single-Ended Ultra/Wide SCSI (PCI)	n/a
X6541A	595-4414	375-0006	Dual Differential Ultra/Wide SCSI (PCI)	n/a

In this article I will be documenting the steps for installing and configuring a Dual Differential Ultra/Wide SCSI (PCI) host adapter (X6541A) in a Sun Blade 150 running Solaris 8.

The above host adapters are designed to be installed in SPARC systems running at least Solaris 2.5.1 Hardware:4/97 operating system.

The host adapters support up to 15 targets on each SCSI bus.

Installing the Dual Differential Ultra/Wide SCSI (PCI)

The following section documents the steps necessary to install a Dual Differential Ultra/Wide SCSI (PCI) (X6541A) in a Sun Blade 150.

Check OS version

Check the file /etc/release to ensure you are running Solaris 2.5.1 or higher.

# cat /etc/release            Solaris 8 2/02 s28s_u7wos_08a SPARC Copyright 2002 Sun Microsystems, Inc.  All Rights Reserved.              Assembled 18 December 2001

Exit the OS and power down the system

Use either the shutdown command (if this is a server with active users that should be warned) or init 0 (if this is a stand along server). When at the ok prompt power down the system.

Unpack host adapter

The following items should be included with your host adapter package:

PCI UltraSCSI host adapter

2 meter UltraSCSI-compliant cable

Electrostatic discharge (ESD) kit

Open the computer

Attach the wrist strap

Attach the wrist strap between your wrist and a metal part of the system chassis.

Disconnect power cord from computer

Remove the filler panel for the desired slot

In most cases this will be just one screw to remove in order to remove the filler panel for the desired PCI slot.

Make sure that the switches and jumpers are correctly set.

For the single-ended host adapter, confirm the following settings:

Make sure that all elements of switches U1 and U2 are off.

Make sure that jumper TP9 is open.

For the differential host adapter, confirm the following settings:

Make sure that all jumpers (TP1, TP2, TP3, TP5, TP6) are open.

Install the host adapter

Install the host adapter into the PCI slot in your system. Ensure to secure the card in with the screw used in the removed filler panel. Using excessive force can bend or damage the pins.

Close up system

Close up the system and remove the anti-static wrist strap.

Reconnect power cable

Connect the SCSI cables

Connect the SCSI cable to your newly installed SCSI host adapter and then to the SCSI peripheral(s).

Power on peripherals / system

Power on your peripherals and then your system.

NOTE: If your system starts to reboot, interrupt the reboot process by pressing the Stop and A keys together. If this is not possible, allow the system to complete the boot process and then bring the system to the ok prompt by using init 0.

Make sure the host adapter is recognized by the system

Use the probe-scsi-all command to display the SCSI devices connected to your system. For example:

ok probe-scsi-all /pci@1f,2000/scsi@2 Target 8 Unit 0 Disk SEAGATE ST34371W SUN4.2G8254 /pci@1f,2000/scsi@2,1 Target 1 Unit 0 Disk SEAGATE ST34371W SUN4.2G8254

In the example, the first SCSI port (scsi@2) has one disk drive connected (target 8). The second SCSI port (scsi@2,1) also has one disk drive connected (target 1).

Reboot your system (using the -r option)

ok boot -r

Test the installation with SunVTS

You can use the SunVTS diagnostic program exercise your system to verify the functionality, reliability, and configuration of the new host adapter card. It is recommended to run the SunVTS program before attempting to utilize the new host adapter for any applications.

The SunVTS program needs to be run as the root userid.

# su

Bring up the SunVTS program (GUI Window):

# /opt/SUNWvts/bin/sunvts

Select a disk drive (any disk) that is attached to the host adapter card you just installed.

Start the test by hitting the "Start" button.

Verify that no errors have occurred by checking the SunVTS status window.

If no problems occur, stop SunVTS by hitting the "Stop" button and exit from the SunVTS application.

Your host adapter card is ready to run applications!

Solstice DiskSuite - (Solaris 2.5.1 - Solaris 8)

2007-01-10T21:09:00.000-08:00

Solstice DiskSuite - (Solaris 2.5.1 - Solaris 8)

Solstice DiskSuite Software Data Sheet - (Solaris 8)
DiskSuite Support Matrix
Introduction
Installing
Command Line Tools
Creating Metadevices - (Using DiskSuite 4.2.1 Commands)
Metadevice State Database - (State Database Replicas)
Creating a Stripe - (RAID 0)
Creating a Concatenation - (RAID 0)
Creating Mirrors - (RAID 1)
Creating a RAID5 Volume - (RAID 5)
Creating a Trans Metadevice
Creating a Hot Spare
Removing Metadevices - (Using DiskSuite 4.2.1 Commands)
Removing a State Database Replica
Removing a Stripe - (RAID 0)
Removing a Concatenation - (RAID 0)
Removing a Mirror - (RAID 1)
Removing a RAID5 Volume - (RAID 5)
Removing a Trans Metadevice
Removing a Hot Spare

Solaris Volume Manager - (Solaris 9)

2007-01-10T21:08:00.001-08:00

Solaris Volume Manager - (Solaris 9)

Solaris Volume Manager Data Sheet - (Solaris 9)
Introduction
Installing
Command Line Tools
Starting the Volume Manager Console GUI - (Enhanced Storage)
Creating Volumes - (Using Solaris 9 Volume Manager Commands)
State Database - (State Database Replicas)
Creating a Stripe - (RAID 0)
Creating a Concatenation - (RAID 0)
Creating Mirrors - (RAID 1)
Creating a RAID5 Volume - (RAID 5)
Creating a Hot Spare
Removing Volumes - (Using Solaris 9 Volume Manager Commands)
Removing a State Database Replica
Removing a Stripe - (RAID 0)
Removing a Concatenation - (RAID 0)
Removing a Mirror - (RAID 1)
Removing a RAID5 Volume - (RAID 5)
Removing a Hot Spare

Using NFS - (Solaris)

2007-01-10T21:06:00.001-08:00

Using NFS - (Solaris)

by Jeff Hunter, Sr. Database Administrator

This brief article touches on several of the important commands that are used to NFS a file system on Solaris. Now keep in mind that with most Solaris configurations; enabling a Sun Solaris server to mount or share a file system, the required daemons will already be running. If not, this article may help you with this process.

The first thing to ensure is that the proper daemons for running NFS are started. If unsure, I will typically just run them when I cannot determine whether or not they are running:

$ su - $ cd /usr/lib/nfs $ ./mountd $ ./nfsd

NOTE:

mountd: RPC server that answers requests for NFS access information and file system mount requests

nfsd: The daemon that handles client file system requests

Sharing A File System

The following example will share a file system /software so that others may be able to mount it:

# share /software

If I want to check all file systems being shared from my system:

# share -               /software   rw   ""

How to NFS A File System

Now, from another machine, I want to NFS the file system that is being shared above:

# mount -F nfs alex:/software /mnt/software

How to Unmount an NFS File System

Finally, let's unmount the previously mounted file system:

# umount /mnt/software

2007-01-10T21:05:00.001-08:00

Determine Which Package a Particular File Belongs To - (Sun Solaris)

by Jeff Hunter, Sr. Database Administrator

Use the pkgchk command to determine which package a particular file belongs to. The syntax is:

# /usr/sbin/pkgchk -l -p /absolute/path/todir

For example,

# /usr/sbin/pkgchk -l -p /usr/bin/pgrep Pathname: /usr/bin/pgrep Type: regular file Expected mode: 0555 Expected owner: root Expected group: bin Expected file size (bytes): 14688 Expected sum(1) of contents: 63968 Expected last modification: Mar 16 05:53:45 AM 2000 Referenced by the following packages:         SUNWcsu Current status: installed

You can also simply query the packages directory as follows:

# grep /usr/bin/pgrep /var/sadm/install/contents /usr/bin/pgrep f none 0555 root bin 14688 63968 953204025 SUNWcsu

Diagnostic Command - (Sun Solaris)

2007-01-10T21:04:00.003-08:00

Diagnostic Command - (Sun Solaris)

by Jeff Hunter, Sr. Database Administrator

prtdiag

Use the following command to obtain detailed diagnostics information about your system configuration:

# /usr/platform/`uname -i`/sbin/prtdiag -v  System Configuration: Sun Microsystems  sun4u Sun Blade 150 (UltraSPARC-IIe 650MHz) System clock frequency: 93 MHZ Memory size: 1.75GB  ==================================== CPUs ====================================                E$          CPU     CPU       Temperature CPU  Freq      Size        Impl.   Mask     Die    Ambient ---  --------  ----------  ------  ----  --------  --------  0    650 MHz  512KB       US-IIe   3.3     56 C     29 C  ================================= IO Devices =================================      Bus   Freq Brd  Type  MHz   Slot        Name                              Model ---  ----  ----  ----------  --------------------------------  ----------------------  0   pci    33            7  isa/dma-isadma (dma)  0   pci    33            7  isa/serial-su16550 (serial)  0   pci    33            7  isa/serial-su16550 (serial)  0   pci    33            8  sound-pci10b9,5451.10b9.5451.1 (+  0   pci    33           12  network-pci108e,1101.1 (network)  SUNW,pci-eri  0   pci    33           12  firewire-pci108e,1102.1001 (fire+  0   pci    33           13  ide-pci10b9,5229.c3 (ide)  0   pci    33           19  SUNW,m64B (display)               ATY,RageXL  ============================ Memory Configuration ============================ Segment Table: ----------------------------------------------------------------------- Base Address       Size       Interleave Factor  Contains ----------------------------------------------------------------------- 0x0                256MB             1           Label DIMM0 0x40000000         512MB             1           Label DIMM1 0x80000000         512MB             1           Label DIMM2 0xc0000000         512MB             1           Label DIMM3  =============================== usb Devices ===============================  Name          Port# ------------  ----- device          4  =============================== device#4 Devices ===============================  Name          Port# ------------  ----- keyboard      mouse ============================ Environmental Status ============================ Fan Speeds: ---------------------------- Fan Device            Speed ---------------------------- system                 100%  ================================ HW Revisions ================================ ASIC Revisions: --------------- ebus: Rev 1  System PROM revisions: ---------------------- OBP 4.6.5 2002/06/03 16:49 POST 2.0.1 2001/08/23 17:13

prtconf

Use the following command to obtain detailed system information about your Sun Solaris installation:

# /usr/sbin/prtconf  System Configuration:  Sun Microsystems  sun4u Memory size: 1792 Megabytes System Peripherals (Software Nodes):  SUNW,Sun-Blade-100     packages (driver not attached)         SUNW,builtin-drivers (driver not attached)         deblocker (driver not attached)         disk-label (driver not attached)         terminal-emulator (driver not attached)         obp-tftp (driver not attached)         dropins (driver not attached)         kbd-translator (driver not attached)         ufs-file-system (driver not attached)     chosen (driver not attached)     openprom (driver not attached)         client-services (driver not attached)     options, instance #0     aliases (driver not attached)     memory (driver not attached)     virtual-memory (driver not attached)     pci, instance #0         ebus, instance #1             flashprom (driver not attached)             eeprom (driver not attached)             idprom (driver not attached)         isa, instance #0             dma, instance #0                 floppy, instance #0                 parallel (driver not attached)             power, instance #0             serial, instance #0             serial, instance #1         network, instance #0         firewire, instance #0         usb (driver not attached)         pmu, instance #0             i2c, instance #0                 temperature, instance #0                 card-reader (driver not attached)                 dimm (driver not attached)                 dimm (driver not attached)                                 dimm (driver not attached)                 dimm (driver not attached)             ppm, instance #0             beep, instance #0             fan-control, instance #0         sound (driver not attached)         ide, instance #0             disk (driver not attached)             cdrom (driver not attached)             dad, instance #0             dad, instance #1             sd, instance #0         pci (driver not attached)         SUNW,m64B, instance #0     SUNW,UltraSPARC-IIe, instance #0     pseudo, instance #0

Using Package Manager on Solaris

2007-01-10T21:04:00.001-08:00

Using Package Manager on Solaris

by Jeff Hunter, Sr. Database Administrator

Adding a Package

  # pkgadd -d samba-2.0.5-sol7-sparc-local

Checking for Packages

  # pkginfo | grep -i samba   application SMCsamba       samba

Removing a Package

  # pkgrm SMCsamba

Configuring Power Management (Sun Blades Only)

2007-01-10T21:03:00.001-08:00

Configuring Power Management (Sun Blades Only)

by Jeff Hunter, Sr. Database Administrator

Hard drive and system power management are adjustable with the dtpower application with Solaris 8 7/01 release and higher. However, the power management features were not present in Solaris 8 10/00 and Solaris 8 1/01 releases. By default, power management is enabled on all new Sun Blade systems. (I really wish Sun would change this!)

When the system is in low-power mode, the hard drive eventually spins down to conserve power. Later, when you perform a task that accesses the hard drive, the hard drive spins up again. You might have to wait a few seconds for the hard drive to spin up to full speed. If you find that the delay is inconvenient, you can turn off Energy Star power management using one of the two methods provided below:

Method #1

You can disable the Energy Star power management feature by using the dtpower application.

# /usr/openwin/bin/dtpower

The dtpower application is displayed.

Under the Current power saving scheme menu, select Disabled.

Press the OK button.

Method #2

The main configuration file for controller Power Management is /etc/power.conf.

As the root user ID, edit the /etc/power.conf file as follows to disable all Automatic Power Management:

# # Copyright (c) 1996 - 2001 by Sun Microsystems, Inc. # All rights reserved. # #pragma ident   "@(#)power.conf 1.14    99/10/18 SMI" # # Power Management Configuration File #  # Statefile     Path statefile               /usr/.CPR   # Auto-Shutdown Idle(min)       Start/Finish(hh:mm)     Behavior autoshutdown    30              9:00 9:00       noshutdown  device-dependency-property removable-media /dev/fb autopm          disable  system-threshold                always-on

Run the command:

# /usr/sbin/pmconfig

This utility is run from the command line after manual changes have been made to the /etc/power.conf file. For editing changes made to the /etc/power.conf file to take effect, users must run pmconfig.

pmconfig is also run at each system boot.

Configuring Telnet / FTP to login as root (Solaris)

2007-01-10T21:02:00.003-08:00

Configuring Telnet / FTP to login as root (Solaris)

by Jeff Hunter, Sr. Database Administrator

Now before getting into the details of how to configure Solaris for root logins, keep in mind that this is VERY BAD security. Make sure that you NEVER configure your production servers for this type of login.

Configure Telnet for root logins

Simply edit the file /etc/default/login and comment out the following line as follows:

# If CONSOLE is set, root can only login on that device. # Comment this line out to allow remote login by root. # # CONSOLE=/dev/console

Configure FTP for root logins

First remove the 'root' line from /etc/ftpusers.

Also, don't forget to edit the file /etc/ftpaccess and comment out the 'deny-uid' and 'deny-gid' lines. If the file doesn't exist, there is no need to create it.

NOTE: If you are using Solaris 9 or Solaris 10, the ftp* files are located in /etc/ftpd

Booting Options and Using EEPROM

2007-01-10T21:02:00.001-08:00

Booting Options and Using EEPROM

by Jeff Hunter, Sr. Database Administrator

EEPROM Command

The eeprom command is located in /usr/sbin/eeprom. The eeprom command is used to display or change the values of parameters in the EEPROM. It processes parameters in the order given. When processing a parameter accompanied by a value, eeprom makes the indicated alteration to the EEPROM; otherwise it displays the parameter's value. When given no parameter specifiers, eeprom displays the values of all EEPROM parameters. A '-' (hyphen) flag specifies that parameters and values are to be read from the standard input (one parameter or parameter = value per line). Only the super-user (root) may alter the EEPROM contents.

When the eeprom command is executed in user mode, the parameters with a trailing question mark (?) need to be enclosed in double quotation marks (" ") to prevent the shell from interpreting the question mark. Preceding the question mark with an escape character (\) will also prevent the shell from interpreting the question mark.

The remainder of this section descibes some of the common usages of the eeprom command in Solaris.

Query Values

To query all current EEPROM values, simply use the eeprom command with no arguments. If you only want to determine one EEPROM value, specify it as an argument. Here are two examples of using the eeprom command:

# eeprom auto-boot? auto-boot?=true # eeprom test-args: data not available. diag-passes=1 pci-probe-list=7,c,3,8,d,13,5 local-mac-address?=false fcode-debug?=false ttyb-rts-dtr-off=false ttyb-ignore-cd=true ttya-rts-dtr-off=false ttya-ignore-cd=true silent-mode?=false scsi-initiator-id=7 oem-logo: data not available. oem-logo?=false oem-banner: data not available. oem-banner?=false ansi-terminal?=true screen-#columns=80 screen-#rows=34 ttyb-mode=9600,8,n,1,- ttya-mode=9600,8,n,1,- output-device=screen input-device=keyboard load-base=16384 auto-boot?=true boot-command=boot diag-file: data not available. diag-device=disk net boot-file: data not available. boot-device=disk net use-nvramrc?=false nvramrc: data not available. security-mode=none security-password: data not available. security-#badlogins=0 mfg-mode=off diag-level=max diag-switch?=false error-reset-recovery=boot

auto-boot?

Used to control the auto-boot feature. This option controls whether the system directly boots up. You can disable auto-boot so next time it stays at the ok prompt for starting installations. Use the following command and reboot the system:

# eeprom "auto-boot?"=false

I/O Bottleneck - Trouble shooting

2006-12-28T02:52:00.001-08:00

What does 100 percent busy mean?

Unix Insider 8/1/99

Q: Some of my disks get really slow when they are nearly 100 percent busy; however, when I see a striped volume or hardware RAID unit at high utilization levels, it still seems to respond quickly. Why is this? Do the old rules about high utilization still apply?

A: This occurs because more complex systems don't obey the same rules as simple systems when it comes to response time, throughput, and utilization. Even the simple systems aren't so simple. I'll begin our examination of this phenomenon by looking at a single disk, and then move on to combinations.

Part of this answer is based on my September 1997 Performance Q&A column. The information from the column was updated and included in my book as of April 1998, and has been further updated for inclusion in Sun BluePrints for Resource Management. Written by several members of our group at Sun, this book will be published this summer (see Resources for more information on both the book and the column). I've added much more explanation and several examples here.

Measurements on a single disk
In an old-style, single-disk model, the device driver maintains a queue of waiting requests that are serviced one at a time by the disk. The terms utilization, service time, wait time, throughput, and wait queue length have well-defined meanings in this scenario; and, for this sort of basic system, the setup is so simple that a very basic queuing model fits it well.

Figure 1. The simple disk model

Over time, disk technology has moved on. Nowadays, a standard disk is SCSI-based and has an embedded controller. The disk drive contains a small microprocessor and about 1 MB of RAM. It can typically handle up to 64 outstanding requests via SCSI tagged-command queuing. The system uses an SCSI host bus adaptor to talk to the disk. In large systems, there is yet another level of intelligence and buffering in a hardware RAID controller. However, the iostat utility is still built around the simple disk model above, and its use of terminology still assumes a single disk that can only handle a single request at a time. In addition, iostat uses the same reporting mechanism for client-side NFS mount points and complex disk volumes set up using Solstice DiskSuite or Veritas Volume Manager.

In the old days, if the device driver sent a request to the disk, the disk would do nothing else until it completed the request. The time this process took was the service time, and the average service time was a physical property of the disk itself. Disks that spun and sought faster had lower (and thus better) service times. With today's systems, if the device driver issues a request, that request is queued internally by the RAID controller and the disk drive, and several more requests can be sent before a response to the first comes back. The service time, as measured by the device driver, varies according to the load level and queue length, and is not directly comparable to the old-style service time of a simple disk drive. The response time is defined as the total waiting time in the queue plus the service time. Unfortunately, as I've mentioned before, iostat reports response time but labels it svc_t. We'll see later how to calculate the actual service time for a disk.

As soon as a device has one request in its internal queue, it becomes busy, and the proportion of the time that it is busy is the utilization. If there is always a request waiting, then the device is 100 percent busy. Because a single disk can only complete one I/O request at a time, it saturates at 100 percent busy. If the device has a large number of requests, and it is intelligent enough to reorder them, it may reduce the average service time and increase the throughput as more load is applied, even though it is already at 100 percent utilization.

The diagram below shows how a busy disk can operate more efficiently than a lightly loaded disk. In practice, the main difference you would see would be a lower service time for the busy disk, albeit with a higher average response time. This is because all the requests are present in the queue at the start, so the response time for the last request includes the time spent waiting for every other request to complete. In the lightly loaded case, each request is serviced as it is made, so there is no waiting, and response time is the same as the service time. If you hear your disk rattling on a desktop system when you start an application, it's because the head is seeking back and forth, as shown in the first case. Unfortunately, starting an application tends to generate a single thread of page-in disk reads. Each such read is not issued until the previous one is completed, so you end up with a fairly busy disk with only one request in the queue -- and it can't be optimized. If the disk is on a busy server instead, there are numerous accesses coming in parallel from different transactions and different users, so you will get a full queue and more efficient disk usage overall.

Figure 2. Disk head movements for a request sequence

Solaris disk instrumentation
The instrumentation provided in the Solaris operating environment takes account of this change by taking a request's waiting period and breaking it up into two separately measured queues. One queue, called the wait queue, is in the device driver; the other, called the active queue, is in the device itself. A read or write command is issued to the device driver and sits in the wait queue until the SCSI bus and disk are both ready. When the command is sent to the disk device, it moves to the active queue until the disk sends its response. The problem with iostat is that it tries to report the new measurements using some of the original terminology. The wait service time is actually the time spent in the wait queue. This isn't the correct definition of service time, in any case, and the word wait is being used to mean two different things.

Figure 3. Two-stage disk model used by Solaris 2

Utilization (U) is defined as the busy time (B) as a percentage of the total time (T) as shown below:

Now, we get to something called service time (S), but this is not what iostat prints out and calls svc_t. This is the real thing! It can be calculated as the busy time (B) divided by the number of accesses that completed, or alternatively as the utilization (U) divided by the throughput (X):

run is as close as you can get to the old-style disk service time; remember, however, that modern disks can queue more than one command at a time and can return them in a different order than the sequence in which they were issued, so it isn't an exact equivalent. To calculate S_run from iostat output, you need to divide the utilization by the total number of reads and writes, as we see here.

  % iostat -xn ...                               extended device statistics   r/s  w/s   kr/s   kw/s wait actv wsvc_t asvc_t   %w   %b device  21.9 63.5 1159.1 2662.9  0.0  2.7    0.0   31.8   0    93 c3t15d0

In this case U = 93% = 0.93, and throughput X = r/s + w/s = 21.9 + 63.5 = 85.4; so, service time S = U/X = 0.011 = 11 milliseconds (ms), while the reported response time R = 31.8 ms. The queue length is reported as 2.7, so this makes sense, as each request has to wait in the queue for several other requests to be serviced.

Using the SE Toolkit, a modified version of iostat written in SE prints out the response time and the service time data, using the format shown below.

  % se siostat.se 10 03:42:50  ------throughput------ -----wait queue----- ----active queue---- disk      r/s  w/s   Kr/s   Kw/s qlen res_t svc_t  %ut qlen res_t svc_t  %ut c0t2d0s0  0.0  0.2    0.0    1.2 0.00  0.02  0.02    0 0.00 22.87 22.87   0 03:43:00  ------throughput------ -----wait queue----- ----active queue---- disk      r/s  w/s   Kr/s   Kw/s qlen res_t svc_t  %ut qlen res_t svc_t  %ut c0t2d0s0  0.0  3.2    0.0   23.1 0.00  0.01  0.01    0 0.72 225.45 16.20   5

We can get the number that iostat calls service time. It's defined as the queue length (Q, shown by iostat with the headings wait and actv) divided by the throughput; but it's actually the residence or response time and includes all queuing effects:

Taking the values from our iostat example, R = Q / X = 2.7 / 85.4 = 0.0316 = 31.6 ms, which is close enough to what iostat reports. The difference between 31.6 and 31.8 is due to rounding errors in the reported values of 2.7 and 85.4. Using full precision, the result is identical to what iostat calculates as the response time.

Another way to express response time is in terms of service time and utilization. This method uses a theoretical model of response time that assumes that, as you approach 100 percent utilization with a constant service time, the response time increases to infinity:

Taking our example again, R = S/(1-U) = 0.011 / (1-0.93) = 0.157 = 157 ms. This is a lot more than the measured response time of 31.8 ms, so the disk is operating better than the simple model predicts at high utilizations. There are several reasons for this: the disk is much more complex than the model; it is actively trying to optimize itself, so the service time isn't constant; and the incoming data isn't as random as the model's assumptions would have it. However, the model does provide the right characteristics, and can be used as a simple way to do a worst-case analysis.

Complex resource utilization characteristics
One important characteristic of complex I/O subsystems is that the utilization measure can be confusing. When a simple system reaches 100 percent busy, it has also reached its maximum throughput. This is because only one thing is being processed at a time in the I/O device. When the device being monitored is an NFS server, a hardware RAID disk subsystem, or a striped volume, the situation is clearly much more complex. All of these can process many requests in parallel.

Figure 4. Complex I/O device queue model

As long as a single I/O is being serviced at all times, the utilization is reported as 100 percent, which makes sense because it means that the pool of devices is always busy doing something. However, there is enough capacity for additional I/Os to be serviced in parallel. Compared to a simple device, the service time for each I/O is the same, but the queue is being drained more quickly; thus, the average queue length and response time are less, and the peak throughput is greater. In effect, the load on each disk is divided by the number of disks; therefore, the true utilization of the striped disk volume is actually above 100 percent. You can see how this arises from the alternative definition of utilization as the throughput multiplied by the service time.

With only one request being serviced at a time, the busy time is the time it takes to service one request multiplied by the number of requests. If several requests can be serviced at once, the calculated utilization goes above 100 percent, because more than one thing can be done at a time! A four-way stripe, with each individual disk 100 percent busy, will have the same service time as one disk, but four times the throughput, and thus should really report up to 400 percent utilization.

The approximated model for response time in this case changes so that response time stays lower for a longer period of time; but it still heads for infinity when the underlying devices each reach 100 percent utilization.

Wrap up
So the real answer to our initial question is that the model of disk behavior and performance that is embodied by the iostat report is too simple to cope with the reality of a complex underlying disk subsystem. We stay with the old report to be consistent and to offer users familiar data, but in reality, a much more sophisticated approach is required. I'm working (slowly) on figuring out how to monitor and report on complex devices like this.

Resources

SE download site: http://www.sun.com/951001/columns/adrian/column2.html
virtual_adrian.se rule: http://www.sun.com/951001/columns/adrian/column2.html
Sun BluePrints Online: The Website that promotes best practices in the datacenter: http://www.sun.com/blueprints
See Adrian Cockcroft's FAQ for answers to three dozen performance-related questions: http://www.itworld.com/Comp/3380/UIR010329cockcroftletters/

Linux Memory Management

2006-12-28T02:30:00.001-08:00

Linux Memory Management

[hide]

[edit]

Overview of memory management

Traditional Unix tools like 'top' often report a surprisingly small amount of free memory after a system has been running for a while. For instance, after about 3 hours of uptime, the machine I'm writing this on reports under 60 MB of free memory, even though I have 512 MB of RAM on the system. Where does it all go?

The biggest place it's being used is in the disk cache, which is currently over 290 MB. This is reported by top as "cached". Cached memory is essentially free, in that it can be replaced quickly if a running (or newly starting) program needs the memory.

The reason Linux uses so much memory for disk cache is because the RAM is wasted if it isn't used. Keeping the cache means that if something needs the same data again, there's a good chance it will still be in the cache in memory. Fetching the information from there is around 1,000 times quicker than getting it from the hard disk. If it's not found in the cache, the hard disk needs to be read anyway, but in that case nothing has been lost in time.

To see a better estimation of how much memory is really free for applications to use, run the command free -m:

Code: free -m

             total       used       free     shared    buffers     cached  Mem:           503        451         52          0         14        293  -/+ buffers/cache:        143        360  Swap:         1027          0       1027

The -/+ buffers/cache line shows how much memory is used and free from the perspective of the applications. Generally speaking, if little swap is being used, memory usage isn't impacting performance at all.

Notice that I have 512 MB of memory in my machine, but only 52 is listed as available by free (this 52 meg is used by the Kernel). This is mainly because the kernel can't be swapped out, so the memory it occupies could never be freed. There may also be regions of memory reserved for/by the hardware for other purposes as well, depending on the system architecture. However, the actualy memory that is free is 360Meg in this case (buffer memory Free).

[edit]

The mysterious 880 MB limit on x86

By default, the Linux kernel runs in and manages only low memory. This makes managing the page tables slightly easier, which in turn makes memory accesses slightly faster. The downside is that it can't use all of the memory once the amount of total RAM reaches the neighborhood of 880 MB. This has historically not been a problem, especially for desktop machines.

To be able to use all the RAM on an 1GB machine or better, the kernel needs to be recompiled. Go into 'make menuconfig' (or whichever config is preferred) and set the following option:

Linux Kernel Configuration: Large amounts of memory

Processor Type and Features ----> High Memory Support ---->  (*) 4GB

This applies both to 2.4 and 2.6 kernels. Turning on high memory support theoretically slows down accesses slightly, but according to Joseph_sys and log, there is no practical difference.

Also, the ck-sources kernel has a patch for 1gb high memory support.

[edit]

The difference among VIRT, RES, and SHR in top output

VIRT stands for the virtual size of a process, which is the sum of memory it is actually using, memory it has mapped into itself (for instance the video card's RAM for the X server), files on disk that have been mapped into it (most notably shared libraries), and memory shared with other processes. VIRT represents how much memory the program is able to access at the present moment.

RES stands for the resident size, which is an accurate representation of how much actual physical memory a process is consuming. (This also corresponds directly to the %MEM column.) This will virtually always be less than the VIRT size, since most programs depend on the C library.

SHR indicates how much of the VIRT size is actually sharable (memory or libraries). In the case of libraries, it does not necessarily mean that the entire library is resident. For example, if a program only uses a few functions in a library, the whole library is mapped and will be counted in VIRT and SHR, but only the parts of the library file containing the functions being used will actually be loaded in and be counted under RES.

[edit]

The difference between buffers and cache

Buffers are allocated by various processes to use as input queues, etc. Most time, buffers are some processes' output, and they are file buffers. A simplistic explanation of buffers is that they allow processes to temporarily store input in memory until the process can deal with it.

Cache is typically frequently requested disk I/O. If multiple processes are accessing the same files, much of those files will be cached to improve performance (RAM being so much faster than hard drives), it's disk cache.

[edit]

Swappiness (2.6 kernels)

Since 2.6, there has been a way to tune how much Linux favors swapping out to disk compared to shrinking the caches when memory gets full.

When an application needs memory and all the RAM is fully occupied, the kernel has two ways to free some memory at its disposal: it can either reduce the disk cache in the RAM by eliminating the oldest data or it may swap some less used portions (pages) of programs out to the swap partition on disk. It is not easy to predict which method would be more efficient. The kernel makes a choice by roughly guessing the effectiveness of the two methods at a given instant, based on the recent history of activity.

Before the 2.6 kernels, the user had no possible means to influence the calculations and there could happen situations where the kernel often made the wrong choice, leading to thrashing and slow performance. The addition of swappiness in 2.6 changes this. Thanks, ghoti!

Swappiness takes a value between 0 and 100 to change the balance between swapping applications and freeing cache. At 100, the kernel will always prefer to find inactive pages and swap them out; in other cases, whether a swapout occurs depends on how much application memory is in use and how poorly the cache is doing at finding and releasing inactive items.

The default swappiness is 60. A value of 0 gives something close to the old behavior where applications that wanted memory could shrink the cache to a tiny fraction of RAM. For laptops which would prefer to let their disk spin down, a value of 20 or less is recommended.

As a sysctl, the swappiness can be set at runtime with either of the following commands:

sysctl -w vm.swappiness=30  echo 30 >/proc/sys/vm/swappiness

The default when Gentoo boots can also be set in /etc/sysctl.conf:

File: /etc/sysctl.conf

# Control how much the kernel should favor swapping out applications (0-100) vm.swappiness = 30

Some patchsets (e.g. Con Kolivas' ck-sources patchset) allow the kernel to auto-tune the swappiness level as it sees fit; they may not keep a user-set value.

[edit]

Autoregulation

gentoo-sources (and probably other gentoo 2.6 kernels) prior to 2.6.7-gentoo contains the Con Kolivas autoregulated swappiness patch. This means that the kernel automatically adjusts the /proc/sys/vm/swappiness value as needed during runtime, so any changes you make will be clobbered next time it updates. A good explanation of this patch and how it works is on KernelTrap.

I repeat: With gentoo-sources (prior to 2.6.7-gentoo) it is neither necessary nor possible to permanently adjust the swappiness value. It's taken care of automatically, no need to worry.

gentoo-sources no longer contains this patch as of 2.6.7-gentoo. The maintainer of gentoo-sources, Greg, pulled the autoregulation patch from the ebuild. http://bugs.gentoo.org/show_bug.cgi?id=54560

INFO ON Promiscuous mode

2006-12-28T02:23:00.001-08:00

INFO ON Promiscuous mode

Promiscuous mode is usually initiated by a network sniffer of some sort. Like Ethereal or dsniff. You may want to check your running processes and verify you're not running something like that or even a trojaned version or something normal. If I saw that in my logs, I would be concerned. You can see promiscuous mode by running /sbin/ifconfig -a

normal: look--> UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1 RX packets:7153852 errors:0 dropped:0 overruns:0 frame:0 TX packets:6107958 errors:0 dropped:0 overruns:0 carrier:14

Promiscuous: look--> UP BROADCAST RUNNING PROMISC MULTICAST MTU:1500 Metric:1 RX packets:7153858 errors:0 dropped:0 overruns:0 frame:0 TX packets:6107962 errors:0 dropped:0 overruns:0 carrier:14

In this case its normal state and can be ignored :

eth0      Link encap:Ethernet HWaddr 00:13:21:07:5A:2B
          inet addr:154.1.33.140 Bcast:154.1.33.255 Mask:255.255.255.128
          UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
          RX packets:15985086 errors:0 dropped:0 overruns:0 frame:0
          TX packets:21467022 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:7258750788 (6922.4 Mb) TX bytes:15187993324 (14484.3 Mb)
          Interrupt:25

eth1      Link encap:Ethernet HWaddr 00:13:21:07:5A:2A
          inet addr:172.18.39.17 Bcast:172.18.39.127 Mask:255.255.255.128
          UP BROADCAST RUNNING MULTICAST MTU:1500 Metric:1
          RX packets:39861538 errors:0 dropped:0 overruns:0 frame:0
          TX packets:78187478 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000
          RX bytes:2552135645 (2433.9 Mb) TX bytes:118484247360 (112995.3 Mb)

Unix Tech Tips & Tricks

Small tutorial on SCCS

Small tutorial on SCCS

The Basics

Setup

Usage

Version info in the source code

Basic Source Control Using RCS

Applying RCS and SCCS

From Source Control to Project Control

Basic Source Control Using RCS

Understanding Virtual Memory -Linux

Understanding Virtual Memory

by Norm Murray and Neil Horman

Introduction

Definitions

What Comprises a VM

MMU

Zoned Buddy Allocator

Slab Allocator

Kernel Threads

The Life of a Page

Tuning the VM

bdflush

dcache_priority

hugetlb_pool

inactive_clean_percent

kswapd

max_map_count

max-readahead

min-readahead

overcommit_memory

overcommit_ratio

pagecache

page-cluster

Example Scenarios

File (IMAP, Web, etc.) Server

General Compute Server With Many Active Users

Non interactive (Batch) Computing Server

Further Reading

Cool Unix Commands

Cool Commands

HOWTO: Mirrored root disk on Solaris

Active FTP vs. Passive FTP, a Definitive Explanation

Configuring TCP/IP on Solaris - Overview of the Booting Processes

Configuring TCP/IP on Solaris - Network Configuration Procedures

Configuring TCP/IP on Solaris - Network Databases and nsswitch.conf File

Networking -- Solaris

Removing Invalid Disk Device Files (/dev/dsk and /dev/rdsk)

Understanding Disk Device Files (i.e. breaking down c0t2d0s7)

Adding SCSI Host Adapter (X6541A) into a Blade 100/150

Solstice DiskSuite - (Solaris 2.5.1 - Solaris 8)

Solaris Volume Manager - (Solaris 9)

Using NFS - (Solaris)

Diagnostic Command - (Sun Solaris)

Using Package Manager on Solaris

Configuring Power Management (Sun Blades Only)

Configuring Telnet / FTP to login as root (Solaris)

Booting Options and Using EEPROM

I/O Bottleneck - Trouble shooting

What does 100 percent busy mean?

Linux Memory Management

Contents

Overview of memory management

The mysterious 880 MB limit on x86

The difference among VIRT, RES, and SHR in top output

The difference between buffers and cache

Swappiness (2.6 kernels)

Autoregulation

INFO ON Promiscuous mode