Wednesday, May 24, 2006
All About OBP
Features of OpenBoot
The OpenBoot architecture provides a significant increase in functionality and portability when compared to proprietary systems of the past. Although this architecture was first implemented by Sun Microsystems as OpenBoot on SPARC systems, its design is processor-independent. Some notable features of OpenBoot firmware include:
• Plug-in device drivers
A plug-in device driver is usually loaded from a plug-in device such as an SBus card. The plug-in device driver can be used to boot the operating system from that device or to display text on the device before the operating
system has activated its own drivers. This feature enables the input and output devices supported by a particular system to evolve without changing the system PROM.
• FCode interpreter
Plug-in drivers are written in a machine-independent interpreted language called FCode. Each OpenBoot system PROM contains an FCode interpreter. Thus, the same device and driver can be used on machines with different CPU instruction sets.
• Device tree
The device tree is a data structure describing the devices (permanently installed and plug-in) attached to a system. Both the user and the operating system can determine the hardware configuration of the system by inspecting the device tree.
• Programmable user interface
The OpenBoot User Interface is based on the interactive programming language Forth. Sequences of user commands can be combined to form complete programs, and this provides a powerful capability for debugging hardware and software.
The User Interface
The user interface is based on an interactive command interpreter that gives you access to an extensive set of functions for hardware and software development, fault isolation, and debugging. Any level of users can use these functions.
The user interface prompt is implementation dependent.
You can enter the OpenBoot environment in the following ways:
• By halting the operating system
• By pressing the Stop-A key
• By power-cycling the system
If your system is not configured to boot automatically, the system will stop at the user interface.
If automatic booting is configured, you can make the system stop at the user interface by pressing the Stop-A keys from the keyboard after the display console banner is displayedbut before the system starts booting the operating system.
• When the system hardware detects an error from which it cannot recover (This is known as a Watchdog Reset.)
See "A Caution About Using Some OpenBoot Commands" ( for information on using commands after entering OpenBoot from the operating system.
The Device Tree
Devices are attached to a host computer through a hierarchy of interconnected buses. OpenBoot represents the interconnected buses and their attached devices as a tree of nodes. Such a tree is called the device tree. A node representing the host computer's main physical address bus forms the tree's root node.
Each device node can have:
• Properties, which are data structures describing the node and its associated device
• Methods, which are the software procedures used to access the device
• Data, which are the initial values of the private data used by the methods
• Children, which are other device nodes "attached" to a given node and that lie directly below it in the device tree
• A parent, which is the node that lies directly above a given node in the device tree.
Nodes with children usually represent buses and their associated controllers, if any. Each such node defines a physical address space that distinguishes the devices connected to the node from one another. Each child of that node is assigned a physical address in the parent's address space.
The physical address generally represents a physical characteristic unique to the device (such as the bus address or the slot number where the device is installed). The use of physical addresses to identify devices prevents device addresses from changing when other devices are installed or removed.
Nodes without children are called leaf nodes and generally represent devices. However, some such nodes represent system-supplied firmware services.
Device Path Names, Addresses, and Arguments
OpenBoot deals directly with hardware devices in the system. Each device has a unique name representing the type of device and where that device is located in the system addressing structure. The following example shows a full device path name:
/sbus@1f,0/SUNW,fas@e,8800000/sd@3,0:a
A full device path name is a series of node names separated by slashes (/). The root of the tree is the machine node, which is not named explicitly but is indicated by a leading slash (/). Each node name has the form:
driver-name@unit-address:device-arguments
driver-name A human-readable string consisting of one to 31 letters, digits and punctuation characters from the set ", . _ + - " that, ideally, has some mnemonic value. Uppercase and lowercase characters are distinct. In some cases, this name includes the name of the device's manufacturer and the device's model name, separated by a comma. Typically, the manufacturer's upper-case, publicly-listed stock symbol is used as the manufacturer's name (e.g. SUNW,sd). For built-in devices, the manufacturer's name is usually omitted (e.g. sbus).
@ Must precede the address parameter.
unit-address A text string representing the physical address of the device in its
parent's address space. The format of the text is bus dependent.
: Must precede the arguments parameter.
device-arguments A text string, whose format depends on the particular device. It can be used to pass additional information to the device's software.
The full device path name mimics the hardware addressing used by the system to distinguish between different devices. Thus, you can specify a particular device without ambiguity.
In general, the unit-address part of a node name represents an address in the physical address space of its parent. The exact meaning of a particular address depends on the bus to which the device is attached. Consider this example:
/sbus@1f,0/esp@0,40000/sd@3,0:a
• 1f,0 represents an address on the main system bus, because the SBus is directly attached to the main system bus in this example.
• 0,40000 is an SBus slot number (in other words, 0) and an offset (in other words, 40000), because the esp device is at offset 40000 on the card in SBus slot 0.
• 3,0 is a SCSI target and logical unit number, because the disk device is attached to a SCSI bus at target 3, logical unit 0.
When specifying a path name, either the @unit-address or driver-name part of a node name is optional, in which case the firmware tries to pick the device that best matches the given name. If there are several matching nodes, the firmware chooses one (but it may not be the one you want).
For example, using /sbus/esp@0,40000/sd@3,0 assumes that the system in question has exactly one SBus on the main system bus, making sbus as unambiguous an address as sbus@1f,0. On the same system, however, /sbus/esp/sd@3,0 might or might not be ambiguous. Since SBus accepts plug-in cards, there could be more than one esp device on the same SBus bus. If there were more than one on the system, using esp alone would not specify which one, and the firmware might not choose the one you intended.
As another example, /sbus/@2,1/sd@3,0 would normally be unambiguous, while /sbus/scsi@2,1/@3,0 usually would not, since both a SCSI disk device driver and a SCSI tape device driver can use the SCSI target, logical unit address 3,0.
The :device-arguments part of the node name is also optional. Once again, in the
example:
/sbus@1f,0/scsi@2,1/sd@3,0:a
the argument for the disk device is a. The software driver for this device interprets its argument as a disk partition, so the device path name refers to partition a on that disk.
Some implementations also enable you to omit path name components. So long as the omission does not create any ambiguity, those implementations will select the device that you intended. For example, if our example system had only one sd device,
/sd:a
would identify the same device as the much longer preceding expression.
Device Aliases
A device alias, or simply, alias, is a shorthand representation of a device path.
For example, the alias disk may represent the complete device path name:
/sbus@1f,0/esp@0,40000/sd@3,0:a
Systems usually have predefined device aliases for the most commonly used devices, so you rarely need to type a full device path name.
Table 2 describes the devalias command, which is used to examine, create, and change aliases.
Table 2 Examining and Creating Device Aliases
Command Description
devalias Display all current device aliases.
devalias alias Display the device path name corresponding to alias.
devalias alias device-path Define an alias representing device-path.
If an alias with the same name already exists, the new value supersedes the old.
User-defined aliases are lost after a system reset or power cycle. If you want to create permanent aliases, you can either manually store the devalias command in a portion of non-volatile RAM (NVRAM) called nvramrc, or use the nvalias and nvunalias commands.
Displaying the Device Tree
You can browse the device tree to examine and modify individual device tree nodes. The device tree browsing commands are similar to the SolarisTM commands for changing, displaying and listing the current directory in the Solaris directory tree. Selecting a device node makes it the current node.
The User Interface commands for browsing the device tree are shown in Table 3.
Command Description
.properties
Display the names and values of the current node's properties.
dev device-path Choose the indicated device node, making it the current node.
dev node-name Search for a node with the given name in the subtree below the current node, and choose the first such node found.
dev .. Choose the device node that is the parent of the current node.
dev / Choose the root machine node.
device-end Leave the device tree.
" device-path" find-device Choose device node, similar to dev.
Ls
Display the names of the current node's children.
Pwd
Display the device path name that names the current node.
see wordname Decompile the specified word.
show-devs [device-path]
Display all the devices directly beneath the specified device in the device tree. show-devs used by itself shows the entire device tree.
Words Display the names of the current node's methods.
" device-path" select-dev Select the specified device and make it the active node.
.properties displays the names and values of all the properties in the current node:
ok dev /zs@1,f0000000
ok .properties
address ffee9000
port-b-ignore-cd
port-a-ignore-cd
keyboard
device_type serial
slave 00000001
intr 0000000c 00000000
interrupts 0000000c
reg 00000001 f0000000 00000008
name zs
ok
dev sets the current node to the named node so its contents can be viewed. For example, to make the ACME company's SBus device named "ACME,widget" the current node:
ok dev /sbus/ACME,widget
find-device is essentially identical to dev differing only in the way the input pathname is passed.
ok " /sbus/ACME,widget" find-device
Note - After choosing a device node with dev or find-device, you can't execute that node's methods because dev does not establish the current instance. For a detailed explanation of this issue, refer toWriting FCode 3.x Programs.
show-devs
lists all the devices in the OpenBoot device tree, as shown in the following example:
ok show-devs
/SUNW,UltraSPARC@0,0
/sbus@1f,0
/counter-timer@1f,3c00
/virtual-memory
/memory@0,0
/aliases
/options
/openprom
/chosen
/packages
/sbus@1f,0/cgsix@1,0
/sbus@1f,0/lebuffer@0,40000
/sbus@1f,0/dma@0,81000
/sbus@1f,0/SUNW,bpp@e,c800000
/sbus@1f,0/SUNW,hme@e,8c00000
/sbus@1f,0/SUNW,fas@e,8800000
/sbus@1f,0/sc@f,1300000
/sbus@1f,0/zs@f,1000000
/sbus@1f,0/zs@f,1100000
/sbus@1f,0/eeprom@f,1200000
/sbus@1f,0/SUNW,fdtwo@f,1400000
/sbus@1f,0/flashprom@f,0
/sbus@1f,0/auxio@f,1900000
/sbus@1f,0/SUNW,CS4231@d,c000000
/sbus@1f,0/SUNW,fas@e,8800000/st
/sbus@1f,0/SUNW,fas@e,8800000/sd
/openprom/client-services
/packages/disk-label
/packages/obp-tftp
/packages/deblocker
/packages/terminal-emulator
ok
Here is an example of the use of words:
ok dev /zs
ok words
ring-bell read remove-abort? install-abort
close open abort? restore
clear reset initkbdmouse keyboard-addr mouse
1200baud setbaud initport port-addr
Getting Help
Whenever you see the ok prompt on the display, you can ask the system for help by typing one of the help commands shown in Table 4.
Table 4 Help Commands
Command Description
Help List main help categories.
help category Show help for all commands in the category. Use only the first word of the category description.
help command Show help for individual command (where available).
help, without any specifier, displays instructions on how to use the help system and lists the available help categories. Because of the large number of commands, help is available only for commands that are used frequently.
If you want to see the help messages for all the commands in a selected category, or, possibly, a list of subcategories, type:
ok help category
If you want help for a specific command, type:
ok help command
For example, when you ask for information on the dump command, you might see the following message:
ok help dump
Category: Memory access
dump ( addr length -- ) display memory at addr for length bytes
ok
The above help message first shows that dump is a command from the Memory access category. The message also shows the format of the command.
Note - In some newer systems, descriptions of additional machine-specific commands are available with the help command. Help as described may not be available on all systems.
A Caution About Using Some OpenBoot Commands
OpenBoot may not operate correctly after the operating system has begun execution. (For example, after Stop-a or halt.) This occurs when the operating system can modify the system state in ways that are inconsistent with continued OpenBoot operation. In this case, you may have to power cycle the system to restore normal operation.
For example, suppose you boot the operating system, exit to OpenBoot, then execute the probe-scsi command (described in "Booting and Testing Your System"). You may find that probe-scsi fails, and you may not be able to resume the operating system, or you may have to power cycle the systems.
Re-execute an OpenBoot command that failed because the operating system has executed:
1. Note the value of auto-boot? NVRAM configuration variable using printenv. If it is true, set the value to false using SETENV.
2. Reset the system.
3. Execute OpenBoot command after it stops at the user interface.
4. Restore the value of auto-boot? NVRAM configuration.
5. Reset the system.
Booting and Testing Your System
This chapter describes the most common tasks that you perform using OpenBoot. These tasks enable you to:
• Boot your system
• Run diagnostics
• Display system information
• Reset the system
Booting Your System
The most important function of OpenBoot firmware is to boot the system. Booting is the process of loading and executing a stand-alone program such as an operating system. Booting can either be initiated automatically or by typing a command at the User Interface.
The boot process is controlled by a number of configuration variables. (Configuration variables are discussed in detail in Chapter 3, "Setting Configuration Variables".) The configuration variables that affect the boot process are:
• auto-boot?
This variable controls whether or not the system automatically boots after a system reset or when the power is turned on. This variable is typically true.
• boot-command
This variable specifies the command to be executed when auto-boot? is true. The default value of boot-command is boot with no command line arguments.
• diag-switch?
If the value is true, run in the Diagnostic mode. This variable is false by default.
• boot-device
This variable contains the name of the default boot device that is used when OpenBoot is not in diagnostic mode.
• boot-file
This variable contains the default boot arguments that are used when OpenBoot is not in diagnostic mode.
• diag-device
This variable contains the name of the default diagnostic mode boot device.
• diag-file
This variable contains the default diagnostic mode boot arguments.
Based on the values of the above configuration variables, the boot process can proceed in a number of different ways. For instance:
• If auto-boot? is true, the machine will boot from either the default boot device or from the diagnostic boot device depending on whether OpenBoot is in diagnostic mode.
• If auto-boot? is false, the machine will stop at the OpenBoot User Interface without booting the system. To boot the system, you can do one of the following:
• Type the boot command without any arguments. The machine will boot from the default boot device using the default boot arguments.
• Type the boot command with an explicit boot device. The machine will boot from the specified boot device using the default boot arguments.
• Type the boot command with explicit boot arguments. The machine will use the specified arguments to boot from the default boot device.
• Type the boot command with an explicit boot device and with explicit arguments. The machine will boot from the specified device with the specified arguments.
Booting for the Casual User
Typically, auto-boot? will be true, boot-command will be boot, and OpenBoot will not be in diagnostic mode. Consequently, the system will automatically load and execute the program and arguments described by boot-file from the device described by boot-device when the system is first turned on or following a system reset.
If you want to boot the default program when auto-boot? is false, simply type boot at the ok prompt.
Booting for the Expert User
Booting is the process of loading and executing a client program. The client program is normally an operating system or an operating system's loader program, but boot can also be used to load and execute other kinds of programs, such as diagnostics.
Booting usually happens automatically based on the values contained in the configuration variables described above. However, the user can also initiate booting from the User Interface.
OpenBoot performs the following steps during the boot process:
• The firmware may reset the machine if a client program has been executed since the last reset. (The execution of a reset is implementation dependent.)
• A device is selected by parsing the boot command line to determine the boot device and the boot arguments to use. Depending on the form of the boot command, the boot device and/or argument values may be taken from configuration variables.
• The bootpath and bootargs properties in the /chosen node of the device tree are set with the selected values.
• The selected program is loaded into memory using a protocol that depends on the type of the selected device. For example, a disk boot might read a fixed number of blocks from the beginning of the disk, while a tape boot might read a particular tape file.
• The loaded program is executed. The behavior of the program may be further controlled by the argument string (if any) that was either contained in the selected configuration variable or was passed to the boot command on the command line.
Often, the program loaded and executed by the boot process is a secondary boot program whose purpose is to load yet another program. This secondary boot program may use a protocol different from that used by OpenBoot to load the secondary boot program. For example, OpenBoot might use the Trivial File Transfer Protocol (TFTP) to load the secondary boot program while the secondary boot program might then use the Network File System (NFS) protocol to load the operating system.
Typical secondary boot programs accept arguments of the form: filename -flags
where filename is the name of the file containing the operating system and where -flags is a list of options controlling the details of the start-up phase of either the secondary boot program, the operating system or both. Please note that, as shown in the boot command template immediately below, OpenBoot treats all such text as a single, opaque arguments string that has no special meaning to OpenBoot itself; the arguments string is passed unaltered to the specified program.
The boot command has the following format:
ok boot [device-specifier] [arguments]
The optional parameters for the boot command are described in Table 5.
Table 5 Optional boot Command Parameters
Parameter Description
[device-specifier] The name (full path name or devalias) of the boot device. Typical values include: cdrom (CD-ROM drive)
disk (hard disk)
floppy (3-1/2" diskette drive)
net (Ethernet)
tape (SCSI tape)
If device-specifier is not specified and if diagnostic-mode? returns false, boot uses the device specified by the boot-device configuration variable. If device-specifier is not specified and if diagnostic-mode? returns true, boot uses the device specified by the diag-device configuration variable.
[arguments] The name of the program to be booted (e.g. stand/diag) and any program arguments. If arguments is not specified and if diagnostic-mode? returns false, boot uses the file specified by the boot-file configuration variable.
If arguments is not specified and if diagnostic-mode? returns true, boot uses the file specified by the diag-file configuration variable.
Note - Most commands (such as boot and test) that require a device name accept either a full device path name or a device alias. In this manual, the term device-specifier indicates that either an appropriate device path name or a device alias is acceptable for such commands.
Since a device alias cannot be syntactically distinguished from the arguments, OpenBoot resolves this ambiguity as follows:
• If the space-delimited word following boot on the command line begins with /, the word is a device-path and, thus, a device-specifier. Any text to the right of this device-specifier is included in arguments.
• Otherwise, if the space-delimited word matches an existing device alias, the word is a device-specifier. Any text to the right of this device-specifier is included in arguments.
• Otherwise, the appropriate default boot device is used, and any text to the right of boot is included in arguments.
Consequently, boot command lines have the following possible forms.
ok boot
With this form, boot loads and executes the program specified by the default boot arguments from the default boot device.
ok boot device-specifier
If boot has a single argument that either begins with the character / or is the name of a defined devalias, boot uses the argument as a device specifier. boot loads and executes the program specified by the default boot arguments from the specified device.
For example, to explicitly boot from the primary disk, type:
ok boot disk
To explicitly boot from the primary network device, type:
ok boot net
If boot has a single argument that neither begins with the character / nor is the name of a defined devalias, boot uses all of the remaining text as its arguments.
ok boot arguments
boot loads and executes the program specified by the arguments from the default boot device.
ok boot device-specifier arguments
If there are at least two space-delimited arguments, and if the first such argument begins with the character / or if it is the name of a defined devalias, boot uses the first argument as a device specifier and uses all of the remaining text as its arguments. boot loads and executes the program specified by the arguments from the specified device.
For all of the above cases, boot records the device that it uses in the bootpath property of the /chosen node. boot also records the arguments that it uses in the bootargs property of the /chosen node.
Device alias definitions vary from system to system. Use the devalias command, described in Chapter 1, "Overview", to obtain the definitions of your system's aliases.
Running Diagnostics
Several diagnostic routines are available from the User Interface. These on-board tests let you check devices such as the network controller, the floppy disk system, memory, installed SBus cards and SCSI devices, and the system clock.
The value returned by diagnostic-mode? controls:
• The selection of the device and file that are used by the boot and load commands (if the device and file are not explicitly specified as arguments to those commands).
• The extent of the diagnostics performed during power-on self-test, and the (implementation dependent) number of diagnostic messages produced.
OpenBoot will be in diagnostic mode and the diagnostic-mode? command will return true if at least one of the following conditions is met:
• The configuration variable diag-switch? is set to true.
• The machine's diagnostic switch (if any) is "on".
• Another system-dependent indicator requests extensive diagnostics.
When OpenBoot is in the Diagnostic mode, the value of diag-device is used as the default boot device and the value of diag-file is used as the default boot arguments for the boot command.
When OpenBoot is not in the Diagnostic mode, the value of boot-device is used as the default boot device and the value of boot-file is used as the default boot arguments for the boot command.
Table 6 lists diagnostic test commands. Not all of these tests are available in all OpenBoot implementations.
Table 6 Diagnostic Test Commands
Command Description
probe-scsi Identify devices attached to a SCSI bus.
test device-specifier Execute the specified device's selftest method. For example: test net - test the network connection
watch-clock Test a clock function.
watch-net Monitor a network connection.
Testing the SCSI Bus
To check a SCSI bus for connected devices, type:
ok probe-scsi
Target 1
Unit 0 Disk SEAGATE ST1480 SUN04246266 Copyright (C) 1991 Seagate All rights reserved
Target 3
Unit 0 Disk SEAGATE ST1480 SUN04245826 Copyright (C) 1991 Seagate All rights reserved
ok
The actual response depends on the devices on the SCSI bus.
Testing Installed Devices
To test a single installed device, type:
ok test device-specifier
In general, if no message is displayed, the test succeeded.
Note - Many devices require the system's diag-switch? parameter to be true in order to run this test.
Testing the Diskette Drive
The diskette drive test determines whether or not the diskette drive is functioning properly. For some implementations, a formatted, high-density (HD) disk must be in the diskette drive for this test to succeed.
To test the diskette drive, type:
ok test floppy
Testing floppy disk system. A formatted
disk should be in the drive.
Test succeeded.
ok
Note - Not all OpenBoot systems include this test word.
To eject the diskette from the diskette drive of a system capable of software-controlled ejection, type:
ok eject-floppy
ok
Testing Memory
To test memory, type:
ok test /memory
Testing 16 megs of memory at addr 4000000 11
ok
Note - Not all OpenBoot systems include this test word.
In the preceding example, the first number (4000000) is the base address of the testing, and the following number (11) is the number of megabytes to go.
Testing the Clock
To test the clock function, type:
ok watch-clock
Watching the 'seconds' register of the real time clock chip.
It should be ticking once a second.
Type any key to stop.
1
ok
The system responds by incrementing a number once a second. Press any key to stop the test.
Note - Not all OpenBoot systems include this test word.
Testing the Network Controller
To test the primary network controller, type:
ok test net
Internal Loopback test - (result)
External Loopback test - (result)
ok
The system responds with a message indicating the result of the test.
Note - Depending on the particular network controller and the type of network to which your system is attached, various levels of testing are possible. Some such tests may require that the network interface be connected to the network.
Monitoring the Network
To monitor a network connection, type:
ok watch-net
Internal Loopback test - succeeded
External Loopback test - succeeded
Looking for Ethernet packets.
'.' is a good packet. 'X' is a bad packet.
Type any key to stop
....................X.....X...............
ok
The system monitors network traffic, displaying "." each time it receives an error-free packet and "X" each time it receives a packet with an error that can be detected by the network hardware interface.
Note - Not all OpenBoot systems include this test word.
Displaying System Information
The User Interface provides one or more commands to display system information. banner is provided by all OpenBoot implementations; the remaining commands represent extensions provided by some implementations. These commands, listed in Table 7, let you display the system banner, the Ethernet address for the Ethernet controller, the contents of the ID PROM, and the version number of OpenBoot. (The ID PROM contains information specific to each individual machine, including the serial number, date of manufacture, and Ethernet address assigned to the machine.)
Table 7 System Information Commands
Command Description
banner Display power-on banner.
show-sbus Display list of installed and probed SBus devices.
.enet-addr Display current Ethernet address.
.idprom Display ID PROM contents, formatted.
Table 7 System Information Commands (Continued)
Command Description
.traps Display a list of processor-dependent trap types.
.version Display version and date of the boot PROM.
.speed Display processor and bus speeds.
Also see the device tree browsing commands in Table 3 on page 7.
Resetting the System
Occasionally, you may need to reset your system. The reset-all command resets the entire system and is similar to performing a power cycle.
To reset the system, type:
ok reset-all
If your system is set up to run the power-on self-test (POST) and initialization procedures on reset, these procedures begin executing once you initiate this command. (On some systems, POST is only executed after power-on.) Once POST completes, the system either boots automatically or enters the User Interface, just as it would have done after a power cycle.
Setting Configuration Variables
This chapter describes how to access and modify non-volatile RAM (NVRAM) configuration variables.
System configuration variables are stored in the system NVRAM. These variables determine the start-up machine configuration and related communication characteristics. You can modify the values of the configuration variables, and any changes you make remain in effect even after a power cycle. Configuration variables should be adjusted cautiously.
The procedures described in this chapter assume that the user interface is active. See Chapter 1, "Overview" for information about entering the user interface.
Table 8 lists a typical set of NVRAM configuration variables defined by IEEE Standard 1275-1994.
Table 8 Standard Configuration Variables
Variable Typical Default Description
auto-boot? true If true, boot automatically after power on or reset.
boot-command boot Command that is executed if auto-boot? is true.
boot-device disk net Device from which to boot.
boot-file empty string Arguments passed to booted program.
diag-device net Diagnostic boot source device.
diag-file empty string Arguments passed to booted program in diagnostic mode.
diag-switch? false If true, run in diagnostic mode.
Table 8 Standard Configuration Variables (Continued)
Variable Typical Default Description
fcode-debug? false If true, include name fields for plug-in device FCodes.
input-device keyboard Console input device (usually keyboard, ttya, or ttyb).
nvramrc empty Contents of NVRAMRC.
oem-banner empty string Custom OEM banner (enabled by oem-banner? true).
oem-banner? false If true, use custom OEM banner.
oem-logo no default Byte array custom OEM logo (enabled by oem-logo? true). Displayed in hexadecimal.
oem-logo? false If true, use custom OEM logo (else, use Sun logo).
output-device screen Console output device (usually screen, ttya, or ttyb).
screen-#columns 80 Number of on-screen columns (characters/line).
screen-#rows 34 Number of on-screen rows (lines).
security-
#badlogins no default Number of incorrect security password attempts.
security-mode none Firmware security level (options: none, command, or full).
security-password no default Firmware security password (never displayed).
use-nvramrc? false If true, execute commands in NVRAMRC during system start-up.
An dditional configuration variable is defined by the SBus binding to IEEE Standard 1275-1994. The variable is shown in Table 9.
Table 9 SBus Configuration Variable
Variable Typical Default Description
sbus-probe-list 0123 Which SBus slots to probe and in what order.
Note - Different OpenBoot implementations may use different defaults and/or different configuration variables.
Displaying and Changing Variable Settings
NVRAM configuration variables can be viewed and changed using the commands listed in
Table 10 Viewing or Changing Configuration Variables
Command Description
printenv Display current variables and current default values. printenv variable shows the current value of the named variable.
setenv variable value Set variable to the given decimal or text value. (Changes are permanent, but often take effect only after a reset.)
set-default variable Reset the value of variable to the factory default.
set-defaults Reset variable values to the factory defaults.
password Set security-password
The following pages show how these commands can be used.
Note - Solaris provides the eeprom utility for modifying OpenBoot configuration variables.
To display a list of the current variable settings on your system, type:
ok printenv
Variable Name Value Default Value
oem-logo 2c 31 2c 2d 00 00 00 00 ...
oem-logo? false false
oem-banner
oem-banner? false false
output-device ttya screen
input-device ttya keyboard
sbus-probe-list 03 0123
diag-file
diag-device net net
boot-file
boot-device disk disk net
auto-boot? false true
fcode-debug? true false
use-nvramrc? false false
nvramrc
screen-#columns 80 80
screen-#rows 34 34
security-mode none none
security-password
security-#badlogins 0
diag-switch? true false
ok
In the displayed, formatted list of the current settings, numeric variables are often shown in decimal.
To change a variable setting, type:
ok setenv variable-name value
variable-name is the name of the variable. value is a numeric value or text string appropriate to the named variable. A numeric value is interpreted as a decimal number, unless preceded by 0x, which is the qualifier for a hexadecimal number.
For example, to set the auto-boot? variable to false, type:
ok setenv auto-boot? false
ok
Note - Many variable changes do not affect the operation of the firmware until the next power cycle or system reset at which time the firmware uses the variable's new value.
You can reset one or most of the variables to the original defaults using the set-default variable and set-defaults commands.
For example, to reset the auto-boot? variable to its default setting (true), type:
ok set-default auto-boot?
ok
To reset most variables to their default settings, type:
ok set-defaults
ok
On SPARC systems, it is possible to reset the NVRAM variables to their default settings by holding down Stop-N while the machine is powering up. When issuing this command, hold down Stop-N immediately after turning on the power to the SPARC system, and keep it pressed for a few seconds or until you see the banner (if the display is available). This is a good technique to force a SPARC compatible machine's NVRAM variables to a known condition.
Setting Security Variables
The NVRAM system security variables are:
• security-mode
• security-password
• security-#badlogins
security-mode can restrict the set of operations that users are allowed to perform from the User Interface. The three security modes, and their available commands, are listed in the following table in the order of most to least secure.
Table 11 Commands Available for security-mode Settings
Mode Commands
full All commands except for go require the password.
command All commands except for boot and go require the password.
none No password required (default).
Command Security
With security-mode set to command:
• A password is not required if you type the boot command by itself. However, if you use the boot command with an argument, a password is required.
• The go command never asks for a password.
• A password is required to execute any other command.
Examples are shown in the following screen.
ok boot (no password required)
ok go (no password required)
ok boot filename (password required)
Password: (password is not echoed as it is typed)
ok reset-all (password required)
Password: (password is not echoed as it is typed)
Caution - It is important to remember your security password and to set the security password before setting the security mode. If you forget this password, you cannot use your system; you must call your vendor's customer support service to make your machine bootable again.
To set the security password and command security mode, type the following at the ok prompt:
ok password
ok New password (only first 8 chars are used):
ok Retype new password:
ok setenv security-mode command
ok
The security password you assign must be between zero and eight characters. Any characters after the eighth are ignored. You do not have to reset the system; the security feature takes effect as soon as you type the command.
If you enter an incorrect security password, there will be a delay of about 10 seconds before the next boot prompt appears. The number of times that an incorrect security password is typed is stored in the security-#badlogins variable.
Full Security
The full security mode is the most restrictive. With security-mode set to full:
• A password is required any time you execute the boot command.
• The go command never asks for a password.
• A password is required to execute any other command.
Here are some examples.
ok go (no password required)
ok boot (password required)
Password: (password is not echoed as it is typed)
ok boot filename (password required)
Password: (password is not echoed as it is typed)
ok reset-all (password required)
Password: (password is not echoed as it is typed)
Caution - It is important to remember your security password and to set the security password before setting the security mode.. If you forget this password, you cannot use your system; you must call your vendor's customer support service to make your machine bootable again.
To set the security password and full security, type the following at the ok prompt:
ok password
ok New password (only first 8 chars are used):
ok Retype new password:
ok setenv security-mode full
ok
Changing the Power-on Banner
The banner configuration variables are:
• oem-banner
• oem-banner?
• oem-logo
• oem-logo?
To view the power-on banner, type:
ok banner
ok
The banner for your system may be different.
The banner consists of two parts: the text field and the logo (over serial ports, only the text field is displayed). You can replace the existing text field with a custom text message using the oem-banner and oem-banner? configuration variables.
To insert a custom text field in the power-on banner, type:
ok setenv oem-banner Hello Mom and Dad ok setenv oem-banner? true
ok banner
ok
The system displays the banner with your new message, as shown in the preceding screen.
The graphic logo is handled differently. oem-logo is a 512-byte array, containing a total of 4096 bits arranged in a 64 x 64 array. Each bit controls one pixel. The most significant bit (MSB) of the first byte controls the upper-left corner pixel. The next bit controls the pixel to the right of it, and so on.
To create a new logo, first create a Forth array containing the correct data; then copy this array into oem-logo. The array is then installed in oem-logo with $setenv. The example below fills the top half of oem-logo with an ascending pattern.
ok create logoarray d# 512 allot
ok logoarray d# 256 0 do i over i + c! loop drop
ok logoarray d# 256 " oem-logo" $setenv
ok setenv oem-logo? true
ok banner
To restore the system's original power-on banner, set the oem-logo? and oem-banner? variables to false.
ok setenv oem-logo? false
ok setenv oem-banner? false
ok
Because the oem-logo array is so large, printenv displays approximately the first 8 bytes (in hexadecimal). To display the entire array, use the phrase oem-logo dump. The oem-logo array is not erased by set-defaults, since it might be difficult to restore the data. However, oem-logo? is set to false when set-defaults executes, so the custom logo is no longer displayed.
Note - Some systems do not support the oem-logo feature.
Input and Output Control
The console is used as the primary means of communication between OpenBoot and the user. The console consists of an input device, used for receiving information supplied by the user, and an output device, used for sending information to the user. Typically, the console is either the combination of a text/graphics display device and a keyboard or an ASCII terminal connected to a serial port.
The configuration variables related to the control of the console are:
• input-device
• output-device
• screen-#columns
• screen-#rows
You can use these variables to assign the power-on defaults for the console. These values do not take effect until after the next power cycle or system reset.
Selecting Input and Output Device Options
The input-device and output-device variables control the firmware's selection of input and output devices after a power-on reset. The default input-device value is keyboard and the default output-device value is screen. The values of input-device and output-device must be device specifiers. The aliases keyboard and screen are often used as the values of these variables.
When the system is reset, the named device becomes the initial firmware console input or output device. (If you want to temporarily change the input or output device, use the input or output commands described in Chapter 4, "Using Forth Tools".)
To set ttya as the initial console input device, type:
ok setenv input-device ttya
ok
If you select keyboard for input-device, and the device is not plugged in, input is accepted from a fallback device (typically ttya) after the next power cycle or system reset. If you select screen for output-device, but no frame buffer is available, output is sent to the fall-back device after the next power cycle or system reset.
To specify an SBus frame buffer as the default output device (especially if there are multiple frame buffers in the system), type:
ok setenv output-device /sbus/SUNW,leo
ok
Serial Port Characteristics
The following values represent the typical range of communications characteristics for serial ports:
• baud = 110, 300, 1200, 2400, 4800, 9600, 19200, or 38400 bits/second
• #bits = 5, 6, 7, or 8 (data bits)
• parity = n (none), e (even), or o (odd), parity bit
• #stop = 1 (1), . (1.5), or 2 (2) stop bits
Note - rts/cts and xon/xoff handshaking are not implemented on some systems. When a selected protocol is not implemented, the handshake variable is accepted but ignored; no messages are displayed.
Selecting Boot Options
You can use the following configuration variable to determine whether or not the
system will boot automatically after a power cycle or system reset.
• auto-boot?
If auto-boot? is true and if OpenBoot is not in diagnostic mode, the system boots automatically after a power-cycle or system reset using the boot-device and boot-file values.
These variables can also be used during manual booting to select the boot device and the program to be booted. For example, to specify default booting from the network server, type:
ok setenv boot-device net
ok
Changes to boot-file and boot-device take effect the next time that boot is executed.
Controlling Power-on Self-Test (POST)
The Power-on Testing variables are:
• diag-switch?
• diag-device
• diag-file
• diag-level
Setting diag-switch? to true causes the function diagnostic-mode? to return true. When diagnostic-mode? returns true, the system:
• Performs more thorough self tests during any subsequent power-on or system reset process.
• May display additional status messages (the details are implementation dependent).
• Uses different configuration variables for booting. (For more details on the effects on the boot process, see Chapter 2, "Booting and Testing Your System".)
Most systems have a factory default of false for the diag-switch? variable. To set diag-switch? to true, type:
ok setenv diag-switch? true
ok
Note - Some systems have a hardware diagnostic switch that also cause diagnostic-mode? to return true. Such systems run the full tests at power-on and system reset if either the hardware switch is set or diag-switch? is true.
Note - Some implementations enable you to force diag-switch? to true by using an implementation-dependent key sequence during power-on. Check your system's documentation for details, or see Appendix C, "Troubleshooting Guide."
To set diag-switch? to false, type:
ok setenv diag-switch? false
ok
When not in diagnostic mode, the system does not announce the diagnostic tests as they are performed (unless a test fails) and may perform fewer tests.
Using nvramrc
The nvramrc configuration variable whose contents are called the script, can be used to store user-defined commands executed during start-up.
Typically, nvramrc is used by a device driver to save start-up configuration variables, to patch device driver code, or to define installation-specific device configuration and device aliases. It can also be used for bug patches or for user-installed extensions. Commands are stored in ASCII, just as the user would type them at the console.
If the use-nvramrc? configuration variable is true, the script is evaluated during the OpenBoot start-up sequence as shown:
• Perform power-on self-test (POST)
• Perform system initialization
• Evaluate the script (if use-nvramrc? is true)
• Execute probe-all (evaluate FCode)
• Execute install-console
• Execute banner
• Execute secondary diagnostics
• Perform default boot (if auto-boot? is true)
It is sometimes desirable to modify the sequence probe-all install-console banner. For example, commands that modify the characteristics of plug-in display devices may need to be executed after the plug-in devices have been probed, but before the console device has been selected. Such commands would need to be executed between probe-all and install-console. Commands that display output on the console would need to be placed after install-console or banner.
This is accomplished by creating a custom script which contains either banner or suppress-banner since the sequence probe-all install-console banner is not executed if either banner or suppress-banner is executed
from the script. This allows the use of probe-all, install-console and banner inside the script, possibly interspersed with other commands, without having those commands re-executed after the script finishes.
Most User Interface commands can be used in the script. The following cannot:
• boot
• go
• nvedit
• password
• reset-all
• setenv security-mode
Editing the Contents of the Script
The script editor, nvedit, lets you create and modify the script using the commands listed in Table 12.
Table 12 Commands Affecting NVRAMAC
Command Description
nvalias alias device-path Stores the command "devalias alias device-path" in the script. The alias persists until either nvunalias or set-defaults is executed.
$nvalias Performs the same function as nvalias except that it takes its arguments, name-string and device-string, from the stack.
nvedit Enters the script editor. If data remains in the temporary buffer from a previous nvedit session, resumes editing those previous contents. If not, reads the contents of nvramrc into the temporary buffer and begins editing it.
nvquit Discards the contents of the temporary buffer, without writing it to nvramrc. Prompts for confirmation.
nvrecover Recovers the contents of nvramrc if they have been lost as a result of the execution of set-defaults; then enters the editor as with nvedit. nvrecover fails if nvedit is executed between the time that the nvramrc contents were lost and the time that nvrecover is executed.
nvrun Executes the contents of the temporary buffer.
nvstore Copies the contents of the temporary buffer to nvramrc; discards the contents of the temporary buffer.
nvunalias alias Deletes the specified alias from nvramrc.
$nvunalias Performs the same function as nvunalias except that it takes its argument, name-string, from the stack.
The editing commands shown in Table 13 are used in the script editor.
Table 13 Script Editor Keystroke Commands
Keystroke Description
Control-B Moves backward one character.
Escape B Moves backward one word.
Control-F Moves forward one character.
Escape F Moves forward one word.
Control-A Moves backward to beginning of the line.
Control-E Moves forward to end of the line.
Control-N Moves to the next line of the script editing buffer.
Control-P Moves to the previous line of the script editing buffer.
Return (Enter) Inserts a new line at the cursor position and advances to the next line.
Control-O Inserts a newline at the cursor position and stays on the current line.
Control-K Erases from the cursor position to the end of the line, storing the erased characters in a save buffer. If at the end of a line, joins the next line to the current line (i.e. deletes the newline).
Delete Erases the previous character.
Backspace Erases the previous character.
Control-H Erases the previous character.
Escape H Erases from beginning of word to just before the cursor, storing erased characters in a save buffer.
Control-W Erases from beginning of word to just before the cursor, storing erased characters in a save buffer.
Control-D Erases the next character.
Escape D Erases from the cursor to the end of the word, storing the erased characters in a save buffer.
Control-U Erases the entire line, storing the erased characters in a save buffer.
Control-Y Inserts the contents of the save buffer before the cursor.
Control-Q Quotes the next character (i.e. allows you to insert control characters).
Control-R Retypes the line.
Control-L Displays the entire contents of the editing buffer.
Control-C Exits the script editor, returning to the OpenBoot command interpreter. The temporary buffer is preserved, but is not written back to the script. (Use nvstore afterwards to write it back.)
Activating the Script
Use the following steps to create and activate the script:
1. At the ok prompt, type nvedit.
Edit the script using editor commands.
2. Type Control-C to get out of the editor and back to the ok prompt.
If you have not yet typed nvstore to save your changes, you may type nvrun to execute the contents of the temporary edit buffer.
3. Type nvstore to save your changes.
4. Enable the interpretation of the script by typing:
setenv use-nvramrc? true
5. Type reset-all to reset the system and execute the script, or type:
nvramrc evaluate
to execute the contents directly.
The following example shows you how to create a simple colon definition in the script.
ok nvedit
0: : hello ( -- )
1: ." Hello, world. " cr
2: ;
3: ^C
ok nvstore
ok setenv use-nvramrc? true
ok reset-all
...
ok hello
Hello, world.
ok
Notice the nvedit line number prompts (0:, 1:, 2:, 3:) in the above example. These prompts are system-dependent.
The OpenBoot architecture provides a significant increase in functionality and portability when compared to proprietary systems of the past. Although this architecture was first implemented by Sun Microsystems as OpenBoot on SPARC systems, its design is processor-independent. Some notable features of OpenBoot firmware include:
• Plug-in device drivers
A plug-in device driver is usually loaded from a plug-in device such as an SBus card. The plug-in device driver can be used to boot the operating system from that device or to display text on the device before the operating
system has activated its own drivers. This feature enables the input and output devices supported by a particular system to evolve without changing the system PROM.
• FCode interpreter
Plug-in drivers are written in a machine-independent interpreted language called FCode. Each OpenBoot system PROM contains an FCode interpreter. Thus, the same device and driver can be used on machines with different CPU instruction sets.
• Device tree
The device tree is a data structure describing the devices (permanently installed and plug-in) attached to a system. Both the user and the operating system can determine the hardware configuration of the system by inspecting the device tree.
• Programmable user interface
The OpenBoot User Interface is based on the interactive programming language Forth. Sequences of user commands can be combined to form complete programs, and this provides a powerful capability for debugging hardware and software.
The User Interface
The user interface is based on an interactive command interpreter that gives you access to an extensive set of functions for hardware and software development, fault isolation, and debugging. Any level of users can use these functions.
The user interface prompt is implementation dependent.
You can enter the OpenBoot environment in the following ways:
• By halting the operating system
• By pressing the Stop-A key
• By power-cycling the system
If your system is not configured to boot automatically, the system will stop at the user interface.
If automatic booting is configured, you can make the system stop at the user interface by pressing the Stop-A keys from the keyboard after the display console banner is displayedbut before the system starts booting the operating system.
• When the system hardware detects an error from which it cannot recover (This is known as a Watchdog Reset.)
See "A Caution About Using Some OpenBoot Commands" ( for information on using commands after entering OpenBoot from the operating system.
The Device Tree
Devices are attached to a host computer through a hierarchy of interconnected buses. OpenBoot represents the interconnected buses and their attached devices as a tree of nodes. Such a tree is called the device tree. A node representing the host computer's main physical address bus forms the tree's root node.
Each device node can have:
• Properties, which are data structures describing the node and its associated device
• Methods, which are the software procedures used to access the device
• Data, which are the initial values of the private data used by the methods
• Children, which are other device nodes "attached" to a given node and that lie directly below it in the device tree
• A parent, which is the node that lies directly above a given node in the device tree.
Nodes with children usually represent buses and their associated controllers, if any. Each such node defines a physical address space that distinguishes the devices connected to the node from one another. Each child of that node is assigned a physical address in the parent's address space.
The physical address generally represents a physical characteristic unique to the device (such as the bus address or the slot number where the device is installed). The use of physical addresses to identify devices prevents device addresses from changing when other devices are installed or removed.
Nodes without children are called leaf nodes and generally represent devices. However, some such nodes represent system-supplied firmware services.
Device Path Names, Addresses, and Arguments
OpenBoot deals directly with hardware devices in the system. Each device has a unique name representing the type of device and where that device is located in the system addressing structure. The following example shows a full device path name:
/sbus@1f,0/SUNW,fas@e,8800000/sd@3,0:a
A full device path name is a series of node names separated by slashes (/). The root of the tree is the machine node, which is not named explicitly but is indicated by a leading slash (/). Each node name has the form:
driver-name@unit-address:device-arguments
driver-name A human-readable string consisting of one to 31 letters, digits and punctuation characters from the set ", . _ + - " that, ideally, has some mnemonic value. Uppercase and lowercase characters are distinct. In some cases, this name includes the name of the device's manufacturer and the device's model name, separated by a comma. Typically, the manufacturer's upper-case, publicly-listed stock symbol is used as the manufacturer's name (e.g. SUNW,sd). For built-in devices, the manufacturer's name is usually omitted (e.g. sbus).
@ Must precede the address parameter.
unit-address A text string representing the physical address of the device in its
parent's address space. The format of the text is bus dependent.
: Must precede the arguments parameter.
device-arguments A text string, whose format depends on the particular device. It can be used to pass additional information to the device's software.
The full device path name mimics the hardware addressing used by the system to distinguish between different devices. Thus, you can specify a particular device without ambiguity.
In general, the unit-address part of a node name represents an address in the physical address space of its parent. The exact meaning of a particular address depends on the bus to which the device is attached. Consider this example:
/sbus@1f,0/esp@0,40000/sd@3,0:a
• 1f,0 represents an address on the main system bus, because the SBus is directly attached to the main system bus in this example.
• 0,40000 is an SBus slot number (in other words, 0) and an offset (in other words, 40000), because the esp device is at offset 40000 on the card in SBus slot 0.
• 3,0 is a SCSI target and logical unit number, because the disk device is attached to a SCSI bus at target 3, logical unit 0.
When specifying a path name, either the @unit-address or driver-name part of a node name is optional, in which case the firmware tries to pick the device that best matches the given name. If there are several matching nodes, the firmware chooses one (but it may not be the one you want).
For example, using /sbus/esp@0,40000/sd@3,0 assumes that the system in question has exactly one SBus on the main system bus, making sbus as unambiguous an address as sbus@1f,0. On the same system, however, /sbus/esp/sd@3,0 might or might not be ambiguous. Since SBus accepts plug-in cards, there could be more than one esp device on the same SBus bus. If there were more than one on the system, using esp alone would not specify which one, and the firmware might not choose the one you intended.
As another example, /sbus/@2,1/sd@3,0 would normally be unambiguous, while /sbus/scsi@2,1/@3,0 usually would not, since both a SCSI disk device driver and a SCSI tape device driver can use the SCSI target, logical unit address 3,0.
The :device-arguments part of the node name is also optional. Once again, in the
example:
/sbus@1f,0/scsi@2,1/sd@3,0:a
the argument for the disk device is a. The software driver for this device interprets its argument as a disk partition, so the device path name refers to partition a on that disk.
Some implementations also enable you to omit path name components. So long as the omission does not create any ambiguity, those implementations will select the device that you intended. For example, if our example system had only one sd device,
/sd:a
would identify the same device as the much longer preceding expression.
Device Aliases
A device alias, or simply, alias, is a shorthand representation of a device path.
For example, the alias disk may represent the complete device path name:
/sbus@1f,0/esp@0,40000/sd@3,0:a
Systems usually have predefined device aliases for the most commonly used devices, so you rarely need to type a full device path name.
Table 2 describes the devalias command, which is used to examine, create, and change aliases.
Table 2 Examining and Creating Device Aliases
Command Description
devalias Display all current device aliases.
devalias alias Display the device path name corresponding to alias.
devalias alias device-path Define an alias representing device-path.
If an alias with the same name already exists, the new value supersedes the old.
User-defined aliases are lost after a system reset or power cycle. If you want to create permanent aliases, you can either manually store the devalias command in a portion of non-volatile RAM (NVRAM) called nvramrc, or use the nvalias and nvunalias commands.
Displaying the Device Tree
You can browse the device tree to examine and modify individual device tree nodes. The device tree browsing commands are similar to the SolarisTM commands for changing, displaying and listing the current directory in the Solaris directory tree. Selecting a device node makes it the current node.
The User Interface commands for browsing the device tree are shown in Table 3.
Command Description
.properties
Display the names and values of the current node's properties.
dev device-path Choose the indicated device node, making it the current node.
dev node-name Search for a node with the given name in the subtree below the current node, and choose the first such node found.
dev .. Choose the device node that is the parent of the current node.
dev / Choose the root machine node.
device-end Leave the device tree.
" device-path" find-device Choose device node, similar to dev.
Ls
Display the names of the current node's children.
Pwd
Display the device path name that names the current node.
see wordname Decompile the specified word.
show-devs [device-path]
Display all the devices directly beneath the specified device in the device tree. show-devs used by itself shows the entire device tree.
Words Display the names of the current node's methods.
" device-path" select-dev Select the specified device and make it the active node.
.properties displays the names and values of all the properties in the current node:
ok dev /zs@1,f0000000
ok .properties
address ffee9000
port-b-ignore-cd
port-a-ignore-cd
keyboard
device_type serial
slave 00000001
intr 0000000c 00000000
interrupts 0000000c
reg 00000001 f0000000 00000008
name zs
ok
dev sets the current node to the named node so its contents can be viewed. For example, to make the ACME company's SBus device named "ACME,widget" the current node:
ok dev /sbus/ACME,widget
find-device is essentially identical to dev differing only in the way the input pathname is passed.
ok " /sbus/ACME,widget" find-device
Note - After choosing a device node with dev or find-device, you can't execute that node's methods because dev does not establish the current instance. For a detailed explanation of this issue, refer toWriting FCode 3.x Programs.
show-devs
lists all the devices in the OpenBoot device tree, as shown in the following example:
ok show-devs
/SUNW,UltraSPARC@0,0
/sbus@1f,0
/counter-timer@1f,3c00
/virtual-memory
/memory@0,0
/aliases
/options
/openprom
/chosen
/packages
/sbus@1f,0/cgsix@1,0
/sbus@1f,0/lebuffer@0,40000
/sbus@1f,0/dma@0,81000
/sbus@1f,0/SUNW,bpp@e,c800000
/sbus@1f,0/SUNW,hme@e,8c00000
/sbus@1f,0/SUNW,fas@e,8800000
/sbus@1f,0/sc@f,1300000
/sbus@1f,0/zs@f,1000000
/sbus@1f,0/zs@f,1100000
/sbus@1f,0/eeprom@f,1200000
/sbus@1f,0/SUNW,fdtwo@f,1400000
/sbus@1f,0/flashprom@f,0
/sbus@1f,0/auxio@f,1900000
/sbus@1f,0/SUNW,CS4231@d,c000000
/sbus@1f,0/SUNW,fas@e,8800000/st
/sbus@1f,0/SUNW,fas@e,8800000/sd
/openprom/client-services
/packages/disk-label
/packages/obp-tftp
/packages/deblocker
/packages/terminal-emulator
ok
Here is an example of the use of words:
ok dev /zs
ok words
ring-bell read remove-abort? install-abort
close open abort? restore
clear reset initkbdmouse keyboard-addr mouse
1200baud setbaud initport port-addr
Getting Help
Whenever you see the ok prompt on the display, you can ask the system for help by typing one of the help commands shown in Table 4.
Table 4 Help Commands
Command Description
Help List main help categories.
help category Show help for all commands in the category. Use only the first word of the category description.
help command Show help for individual command (where available).
help, without any specifier, displays instructions on how to use the help system and lists the available help categories. Because of the large number of commands, help is available only for commands that are used frequently.
If you want to see the help messages for all the commands in a selected category, or, possibly, a list of subcategories, type:
ok help category
If you want help for a specific command, type:
ok help command
For example, when you ask for information on the dump command, you might see the following message:
ok help dump
Category: Memory access
dump ( addr length -- ) display memory at addr for length bytes
ok
The above help message first shows that dump is a command from the Memory access category. The message also shows the format of the command.
Note - In some newer systems, descriptions of additional machine-specific commands are available with the help command. Help as described may not be available on all systems.
A Caution About Using Some OpenBoot Commands
OpenBoot may not operate correctly after the operating system has begun execution. (For example, after Stop-a or halt.) This occurs when the operating system can modify the system state in ways that are inconsistent with continued OpenBoot operation. In this case, you may have to power cycle the system to restore normal operation.
For example, suppose you boot the operating system, exit to OpenBoot, then execute the probe-scsi command (described in "Booting and Testing Your System"). You may find that probe-scsi fails, and you may not be able to resume the operating system, or you may have to power cycle the systems.
Re-execute an OpenBoot command that failed because the operating system has executed:
1. Note the value of auto-boot? NVRAM configuration variable using printenv. If it is true, set the value to false using SETENV.
2. Reset the system.
3. Execute OpenBoot command after it stops at the user interface.
4. Restore the value of auto-boot? NVRAM configuration.
5. Reset the system.
Booting and Testing Your System
This chapter describes the most common tasks that you perform using OpenBoot. These tasks enable you to:
• Boot your system
• Run diagnostics
• Display system information
• Reset the system
Booting Your System
The most important function of OpenBoot firmware is to boot the system. Booting is the process of loading and executing a stand-alone program such as an operating system. Booting can either be initiated automatically or by typing a command at the User Interface.
The boot process is controlled by a number of configuration variables. (Configuration variables are discussed in detail in Chapter 3, "Setting Configuration Variables".) The configuration variables that affect the boot process are:
• auto-boot?
This variable controls whether or not the system automatically boots after a system reset or when the power is turned on. This variable is typically true.
• boot-command
This variable specifies the command to be executed when auto-boot? is true. The default value of boot-command is boot with no command line arguments.
• diag-switch?
If the value is true, run in the Diagnostic mode. This variable is false by default.
• boot-device
This variable contains the name of the default boot device that is used when OpenBoot is not in diagnostic mode.
• boot-file
This variable contains the default boot arguments that are used when OpenBoot is not in diagnostic mode.
• diag-device
This variable contains the name of the default diagnostic mode boot device.
• diag-file
This variable contains the default diagnostic mode boot arguments.
Based on the values of the above configuration variables, the boot process can proceed in a number of different ways. For instance:
• If auto-boot? is true, the machine will boot from either the default boot device or from the diagnostic boot device depending on whether OpenBoot is in diagnostic mode.
• If auto-boot? is false, the machine will stop at the OpenBoot User Interface without booting the system. To boot the system, you can do one of the following:
• Type the boot command without any arguments. The machine will boot from the default boot device using the default boot arguments.
• Type the boot command with an explicit boot device. The machine will boot from the specified boot device using the default boot arguments.
• Type the boot command with explicit boot arguments. The machine will use the specified arguments to boot from the default boot device.
• Type the boot command with an explicit boot device and with explicit arguments. The machine will boot from the specified device with the specified arguments.
Booting for the Casual User
Typically, auto-boot? will be true, boot-command will be boot, and OpenBoot will not be in diagnostic mode. Consequently, the system will automatically load and execute the program and arguments described by boot-file from the device described by boot-device when the system is first turned on or following a system reset.
If you want to boot the default program when auto-boot? is false, simply type boot at the ok prompt.
Booting for the Expert User
Booting is the process of loading and executing a client program. The client program is normally an operating system or an operating system's loader program, but boot can also be used to load and execute other kinds of programs, such as diagnostics.
Booting usually happens automatically based on the values contained in the configuration variables described above. However, the user can also initiate booting from the User Interface.
OpenBoot performs the following steps during the boot process:
• The firmware may reset the machine if a client program has been executed since the last reset. (The execution of a reset is implementation dependent.)
• A device is selected by parsing the boot command line to determine the boot device and the boot arguments to use. Depending on the form of the boot command, the boot device and/or argument values may be taken from configuration variables.
• The bootpath and bootargs properties in the /chosen node of the device tree are set with the selected values.
• The selected program is loaded into memory using a protocol that depends on the type of the selected device. For example, a disk boot might read a fixed number of blocks from the beginning of the disk, while a tape boot might read a particular tape file.
• The loaded program is executed. The behavior of the program may be further controlled by the argument string (if any) that was either contained in the selected configuration variable or was passed to the boot command on the command line.
Often, the program loaded and executed by the boot process is a secondary boot program whose purpose is to load yet another program. This secondary boot program may use a protocol different from that used by OpenBoot to load the secondary boot program. For example, OpenBoot might use the Trivial File Transfer Protocol (TFTP) to load the secondary boot program while the secondary boot program might then use the Network File System (NFS) protocol to load the operating system.
Typical secondary boot programs accept arguments of the form: filename -flags
where filename is the name of the file containing the operating system and where -flags is a list of options controlling the details of the start-up phase of either the secondary boot program, the operating system or both. Please note that, as shown in the boot command template immediately below, OpenBoot treats all such text as a single, opaque arguments string that has no special meaning to OpenBoot itself; the arguments string is passed unaltered to the specified program.
The boot command has the following format:
ok boot [device-specifier] [arguments]
The optional parameters for the boot command are described in Table 5.
Table 5 Optional boot Command Parameters
Parameter Description
[device-specifier] The name (full path name or devalias) of the boot device. Typical values include: cdrom (CD-ROM drive)
disk (hard disk)
floppy (3-1/2" diskette drive)
net (Ethernet)
tape (SCSI tape)
If device-specifier is not specified and if diagnostic-mode? returns false, boot uses the device specified by the boot-device configuration variable. If device-specifier is not specified and if diagnostic-mode? returns true, boot uses the device specified by the diag-device configuration variable.
[arguments] The name of the program to be booted (e.g. stand/diag) and any program arguments. If arguments is not specified and if diagnostic-mode? returns false, boot uses the file specified by the boot-file configuration variable.
If arguments is not specified and if diagnostic-mode? returns true, boot uses the file specified by the diag-file configuration variable.
Note - Most commands (such as boot and test) that require a device name accept either a full device path name or a device alias. In this manual, the term device-specifier indicates that either an appropriate device path name or a device alias is acceptable for such commands.
Since a device alias cannot be syntactically distinguished from the arguments, OpenBoot resolves this ambiguity as follows:
• If the space-delimited word following boot on the command line begins with /, the word is a device-path and, thus, a device-specifier. Any text to the right of this device-specifier is included in arguments.
• Otherwise, if the space-delimited word matches an existing device alias, the word is a device-specifier. Any text to the right of this device-specifier is included in arguments.
• Otherwise, the appropriate default boot device is used, and any text to the right of boot is included in arguments.
Consequently, boot command lines have the following possible forms.
ok boot
With this form, boot loads and executes the program specified by the default boot arguments from the default boot device.
ok boot device-specifier
If boot has a single argument that either begins with the character / or is the name of a defined devalias, boot uses the argument as a device specifier. boot loads and executes the program specified by the default boot arguments from the specified device.
For example, to explicitly boot from the primary disk, type:
ok boot disk
To explicitly boot from the primary network device, type:
ok boot net
If boot has a single argument that neither begins with the character / nor is the name of a defined devalias, boot uses all of the remaining text as its arguments.
ok boot arguments
boot loads and executes the program specified by the arguments from the default boot device.
ok boot device-specifier arguments
If there are at least two space-delimited arguments, and if the first such argument begins with the character / or if it is the name of a defined devalias, boot uses the first argument as a device specifier and uses all of the remaining text as its arguments. boot loads and executes the program specified by the arguments from the specified device.
For all of the above cases, boot records the device that it uses in the bootpath property of the /chosen node. boot also records the arguments that it uses in the bootargs property of the /chosen node.
Device alias definitions vary from system to system. Use the devalias command, described in Chapter 1, "Overview", to obtain the definitions of your system's aliases.
Running Diagnostics
Several diagnostic routines are available from the User Interface. These on-board tests let you check devices such as the network controller, the floppy disk system, memory, installed SBus cards and SCSI devices, and the system clock.
The value returned by diagnostic-mode? controls:
• The selection of the device and file that are used by the boot and load commands (if the device and file are not explicitly specified as arguments to those commands).
• The extent of the diagnostics performed during power-on self-test, and the (implementation dependent) number of diagnostic messages produced.
OpenBoot will be in diagnostic mode and the diagnostic-mode? command will return true if at least one of the following conditions is met:
• The configuration variable diag-switch? is set to true.
• The machine's diagnostic switch (if any) is "on".
• Another system-dependent indicator requests extensive diagnostics.
When OpenBoot is in the Diagnostic mode, the value of diag-device is used as the default boot device and the value of diag-file is used as the default boot arguments for the boot command.
When OpenBoot is not in the Diagnostic mode, the value of boot-device is used as the default boot device and the value of boot-file is used as the default boot arguments for the boot command.
Table 6 lists diagnostic test commands. Not all of these tests are available in all OpenBoot implementations.
Table 6 Diagnostic Test Commands
Command Description
probe-scsi Identify devices attached to a SCSI bus.
test device-specifier Execute the specified device's selftest method. For example: test net - test the network connection
watch-clock Test a clock function.
watch-net Monitor a network connection.
Testing the SCSI Bus
To check a SCSI bus for connected devices, type:
ok probe-scsi
Target 1
Unit 0 Disk SEAGATE ST1480 SUN04246266 Copyright (C) 1991 Seagate All rights reserved
Target 3
Unit 0 Disk SEAGATE ST1480 SUN04245826 Copyright (C) 1991 Seagate All rights reserved
ok
The actual response depends on the devices on the SCSI bus.
Testing Installed Devices
To test a single installed device, type:
ok test device-specifier
In general, if no message is displayed, the test succeeded.
Note - Many devices require the system's diag-switch? parameter to be true in order to run this test.
Testing the Diskette Drive
The diskette drive test determines whether or not the diskette drive is functioning properly. For some implementations, a formatted, high-density (HD) disk must be in the diskette drive for this test to succeed.
To test the diskette drive, type:
ok test floppy
Testing floppy disk system. A formatted
disk should be in the drive.
Test succeeded.
ok
Note - Not all OpenBoot systems include this test word.
To eject the diskette from the diskette drive of a system capable of software-controlled ejection, type:
ok eject-floppy
ok
Testing Memory
To test memory, type:
ok test /memory
Testing 16 megs of memory at addr 4000000 11
ok
Note - Not all OpenBoot systems include this test word.
In the preceding example, the first number (4000000) is the base address of the testing, and the following number (11) is the number of megabytes to go.
Testing the Clock
To test the clock function, type:
ok watch-clock
Watching the 'seconds' register of the real time clock chip.
It should be ticking once a second.
Type any key to stop.
1
ok
The system responds by incrementing a number once a second. Press any key to stop the test.
Note - Not all OpenBoot systems include this test word.
Testing the Network Controller
To test the primary network controller, type:
ok test net
Internal Loopback test - (result)
External Loopback test - (result)
ok
The system responds with a message indicating the result of the test.
Note - Depending on the particular network controller and the type of network to which your system is attached, various levels of testing are possible. Some such tests may require that the network interface be connected to the network.
Monitoring the Network
To monitor a network connection, type:
ok watch-net
Internal Loopback test - succeeded
External Loopback test - succeeded
Looking for Ethernet packets.
'.' is a good packet. 'X' is a bad packet.
Type any key to stop
....................X.....X...............
ok
The system monitors network traffic, displaying "." each time it receives an error-free packet and "X" each time it receives a packet with an error that can be detected by the network hardware interface.
Note - Not all OpenBoot systems include this test word.
Displaying System Information
The User Interface provides one or more commands to display system information. banner is provided by all OpenBoot implementations; the remaining commands represent extensions provided by some implementations. These commands, listed in Table 7, let you display the system banner, the Ethernet address for the Ethernet controller, the contents of the ID PROM, and the version number of OpenBoot. (The ID PROM contains information specific to each individual machine, including the serial number, date of manufacture, and Ethernet address assigned to the machine.)
Table 7 System Information Commands
Command Description
banner Display power-on banner.
show-sbus Display list of installed and probed SBus devices.
.enet-addr Display current Ethernet address.
.idprom Display ID PROM contents, formatted.
Table 7 System Information Commands (Continued)
Command Description
.traps Display a list of processor-dependent trap types.
.version Display version and date of the boot PROM.
.speed Display processor and bus speeds.
Also see the device tree browsing commands in Table 3 on page 7.
Resetting the System
Occasionally, you may need to reset your system. The reset-all command resets the entire system and is similar to performing a power cycle.
To reset the system, type:
ok reset-all
If your system is set up to run the power-on self-test (POST) and initialization procedures on reset, these procedures begin executing once you initiate this command. (On some systems, POST is only executed after power-on.) Once POST completes, the system either boots automatically or enters the User Interface, just as it would have done after a power cycle.
Setting Configuration Variables
This chapter describes how to access and modify non-volatile RAM (NVRAM) configuration variables.
System configuration variables are stored in the system NVRAM. These variables determine the start-up machine configuration and related communication characteristics. You can modify the values of the configuration variables, and any changes you make remain in effect even after a power cycle. Configuration variables should be adjusted cautiously.
The procedures described in this chapter assume that the user interface is active. See Chapter 1, "Overview" for information about entering the user interface.
Table 8 lists a typical set of NVRAM configuration variables defined by IEEE Standard 1275-1994.
Table 8 Standard Configuration Variables
Variable Typical Default Description
auto-boot? true If true, boot automatically after power on or reset.
boot-command boot Command that is executed if auto-boot? is true.
boot-device disk net Device from which to boot.
boot-file empty string Arguments passed to booted program.
diag-device net Diagnostic boot source device.
diag-file empty string Arguments passed to booted program in diagnostic mode.
diag-switch? false If true, run in diagnostic mode.
Table 8 Standard Configuration Variables (Continued)
Variable Typical Default Description
fcode-debug? false If true, include name fields for plug-in device FCodes.
input-device keyboard Console input device (usually keyboard, ttya, or ttyb).
nvramrc empty Contents of NVRAMRC.
oem-banner empty string Custom OEM banner (enabled by oem-banner? true).
oem-banner? false If true, use custom OEM banner.
oem-logo no default Byte array custom OEM logo (enabled by oem-logo? true). Displayed in hexadecimal.
oem-logo? false If true, use custom OEM logo (else, use Sun logo).
output-device screen Console output device (usually screen, ttya, or ttyb).
screen-#columns 80 Number of on-screen columns (characters/line).
screen-#rows 34 Number of on-screen rows (lines).
security-
#badlogins no default Number of incorrect security password attempts.
security-mode none Firmware security level (options: none, command, or full).
security-password no default Firmware security password (never displayed).
use-nvramrc? false If true, execute commands in NVRAMRC during system start-up.
An dditional configuration variable is defined by the SBus binding to IEEE Standard 1275-1994. The variable is shown in Table 9.
Table 9 SBus Configuration Variable
Variable Typical Default Description
sbus-probe-list 0123 Which SBus slots to probe and in what order.
Note - Different OpenBoot implementations may use different defaults and/or different configuration variables.
Displaying and Changing Variable Settings
NVRAM configuration variables can be viewed and changed using the commands listed in
Table 10 Viewing or Changing Configuration Variables
Command Description
printenv Display current variables and current default values. printenv variable shows the current value of the named variable.
setenv variable value Set variable to the given decimal or text value. (Changes are permanent, but often take effect only after a reset.)
set-default variable Reset the value of variable to the factory default.
set-defaults Reset variable values to the factory defaults.
password Set security-password
The following pages show how these commands can be used.
Note - Solaris provides the eeprom utility for modifying OpenBoot configuration variables.
To display a list of the current variable settings on your system, type:
ok printenv
Variable Name Value Default Value
oem-logo 2c 31 2c 2d 00 00 00 00 ...
oem-logo? false false
oem-banner
oem-banner? false false
output-device ttya screen
input-device ttya keyboard
sbus-probe-list 03 0123
diag-file
diag-device net net
boot-file
boot-device disk disk net
auto-boot? false true
fcode-debug? true false
use-nvramrc? false false
nvramrc
screen-#columns 80 80
screen-#rows 34 34
security-mode none none
security-password
security-#badlogins 0
diag-switch? true false
ok
In the displayed, formatted list of the current settings, numeric variables are often shown in decimal.
To change a variable setting, type:
ok setenv variable-name value
variable-name is the name of the variable. value is a numeric value or text string appropriate to the named variable. A numeric value is interpreted as a decimal number, unless preceded by 0x, which is the qualifier for a hexadecimal number.
For example, to set the auto-boot? variable to false, type:
ok setenv auto-boot? false
ok
Note - Many variable changes do not affect the operation of the firmware until the next power cycle or system reset at which time the firmware uses the variable's new value.
You can reset one or most of the variables to the original defaults using the set-default variable and set-defaults commands.
For example, to reset the auto-boot? variable to its default setting (true), type:
ok set-default auto-boot?
ok
To reset most variables to their default settings, type:
ok set-defaults
ok
On SPARC systems, it is possible to reset the NVRAM variables to their default settings by holding down Stop-N while the machine is powering up. When issuing this command, hold down Stop-N immediately after turning on the power to the SPARC system, and keep it pressed for a few seconds or until you see the banner (if the display is available). This is a good technique to force a SPARC compatible machine's NVRAM variables to a known condition.
Setting Security Variables
The NVRAM system security variables are:
• security-mode
• security-password
• security-#badlogins
security-mode can restrict the set of operations that users are allowed to perform from the User Interface. The three security modes, and their available commands, are listed in the following table in the order of most to least secure.
Table 11 Commands Available for security-mode Settings
Mode Commands
full All commands except for go require the password.
command All commands except for boot and go require the password.
none No password required (default).
Command Security
With security-mode set to command:
• A password is not required if you type the boot command by itself. However, if you use the boot command with an argument, a password is required.
• The go command never asks for a password.
• A password is required to execute any other command.
Examples are shown in the following screen.
ok boot (no password required)
ok go (no password required)
ok boot filename (password required)
Password: (password is not echoed as it is typed)
ok reset-all (password required)
Password: (password is not echoed as it is typed)
Caution - It is important to remember your security password and to set the security password before setting the security mode. If you forget this password, you cannot use your system; you must call your vendor's customer support service to make your machine bootable again.
To set the security password and command security mode, type the following at the ok prompt:
ok password
ok New password (only first 8 chars are used):
ok Retype new password:
ok setenv security-mode command
ok
The security password you assign must be between zero and eight characters. Any characters after the eighth are ignored. You do not have to reset the system; the security feature takes effect as soon as you type the command.
If you enter an incorrect security password, there will be a delay of about 10 seconds before the next boot prompt appears. The number of times that an incorrect security password is typed is stored in the security-#badlogins variable.
Full Security
The full security mode is the most restrictive. With security-mode set to full:
• A password is required any time you execute the boot command.
• The go command never asks for a password.
• A password is required to execute any other command.
Here are some examples.
ok go (no password required)
ok boot (password required)
Password: (password is not echoed as it is typed)
ok boot filename (password required)
Password: (password is not echoed as it is typed)
ok reset-all (password required)
Password: (password is not echoed as it is typed)
Caution - It is important to remember your security password and to set the security password before setting the security mode.. If you forget this password, you cannot use your system; you must call your vendor's customer support service to make your machine bootable again.
To set the security password and full security, type the following at the ok prompt:
ok password
ok New password (only first 8 chars are used):
ok Retype new password:
ok setenv security-mode full
ok
Changing the Power-on Banner
The banner configuration variables are:
• oem-banner
• oem-banner?
• oem-logo
• oem-logo?
To view the power-on banner, type:
ok banner
ok
The banner for your system may be different.
The banner consists of two parts: the text field and the logo (over serial ports, only the text field is displayed). You can replace the existing text field with a custom text message using the oem-banner and oem-banner? configuration variables.
To insert a custom text field in the power-on banner, type:
ok setenv oem-banner Hello Mom and Dad ok setenv oem-banner? true
ok banner
ok
The system displays the banner with your new message, as shown in the preceding screen.
The graphic logo is handled differently. oem-logo is a 512-byte array, containing a total of 4096 bits arranged in a 64 x 64 array. Each bit controls one pixel. The most significant bit (MSB) of the first byte controls the upper-left corner pixel. The next bit controls the pixel to the right of it, and so on.
To create a new logo, first create a Forth array containing the correct data; then copy this array into oem-logo. The array is then installed in oem-logo with $setenv. The example below fills the top half of oem-logo with an ascending pattern.
ok create logoarray d# 512 allot
ok logoarray d# 256 0 do i over i + c! loop drop
ok logoarray d# 256 " oem-logo" $setenv
ok setenv oem-logo? true
ok banner
To restore the system's original power-on banner, set the oem-logo? and oem-banner? variables to false.
ok setenv oem-logo? false
ok setenv oem-banner? false
ok
Because the oem-logo array is so large, printenv displays approximately the first 8 bytes (in hexadecimal). To display the entire array, use the phrase oem-logo dump. The oem-logo array is not erased by set-defaults, since it might be difficult to restore the data. However, oem-logo? is set to false when set-defaults executes, so the custom logo is no longer displayed.
Note - Some systems do not support the oem-logo feature.
Input and Output Control
The console is used as the primary means of communication between OpenBoot and the user. The console consists of an input device, used for receiving information supplied by the user, and an output device, used for sending information to the user. Typically, the console is either the combination of a text/graphics display device and a keyboard or an ASCII terminal connected to a serial port.
The configuration variables related to the control of the console are:
• input-device
• output-device
• screen-#columns
• screen-#rows
You can use these variables to assign the power-on defaults for the console. These values do not take effect until after the next power cycle or system reset.
Selecting Input and Output Device Options
The input-device and output-device variables control the firmware's selection of input and output devices after a power-on reset. The default input-device value is keyboard and the default output-device value is screen. The values of input-device and output-device must be device specifiers. The aliases keyboard and screen are often used as the values of these variables.
When the system is reset, the named device becomes the initial firmware console input or output device. (If you want to temporarily change the input or output device, use the input or output commands described in Chapter 4, "Using Forth Tools".)
To set ttya as the initial console input device, type:
ok setenv input-device ttya
ok
If you select keyboard for input-device, and the device is not plugged in, input is accepted from a fallback device (typically ttya) after the next power cycle or system reset. If you select screen for output-device, but no frame buffer is available, output is sent to the fall-back device after the next power cycle or system reset.
To specify an SBus frame buffer as the default output device (especially if there are multiple frame buffers in the system), type:
ok setenv output-device /sbus/SUNW,leo
ok
Serial Port Characteristics
The following values represent the typical range of communications characteristics for serial ports:
• baud = 110, 300, 1200, 2400, 4800, 9600, 19200, or 38400 bits/second
• #bits = 5, 6, 7, or 8 (data bits)
• parity = n (none), e (even), or o (odd), parity bit
• #stop = 1 (1), . (1.5), or 2 (2) stop bits
Note - rts/cts and xon/xoff handshaking are not implemented on some systems. When a selected protocol is not implemented, the handshake variable is accepted but ignored; no messages are displayed.
Selecting Boot Options
You can use the following configuration variable to determine whether or not the
system will boot automatically after a power cycle or system reset.
• auto-boot?
If auto-boot? is true and if OpenBoot is not in diagnostic mode, the system boots automatically after a power-cycle or system reset using the boot-device and boot-file values.
These variables can also be used during manual booting to select the boot device and the program to be booted. For example, to specify default booting from the network server, type:
ok setenv boot-device net
ok
Changes to boot-file and boot-device take effect the next time that boot is executed.
Controlling Power-on Self-Test (POST)
The Power-on Testing variables are:
• diag-switch?
• diag-device
• diag-file
• diag-level
Setting diag-switch? to true causes the function diagnostic-mode? to return true. When diagnostic-mode? returns true, the system:
• Performs more thorough self tests during any subsequent power-on or system reset process.
• May display additional status messages (the details are implementation dependent).
• Uses different configuration variables for booting. (For more details on the effects on the boot process, see Chapter 2, "Booting and Testing Your System".)
Most systems have a factory default of false for the diag-switch? variable. To set diag-switch? to true, type:
ok setenv diag-switch? true
ok
Note - Some systems have a hardware diagnostic switch that also cause diagnostic-mode? to return true. Such systems run the full tests at power-on and system reset if either the hardware switch is set or diag-switch? is true.
Note - Some implementations enable you to force diag-switch? to true by using an implementation-dependent key sequence during power-on. Check your system's documentation for details, or see Appendix C, "Troubleshooting Guide."
To set diag-switch? to false, type:
ok setenv diag-switch? false
ok
When not in diagnostic mode, the system does not announce the diagnostic tests as they are performed (unless a test fails) and may perform fewer tests.
Using nvramrc
The nvramrc configuration variable whose contents are called the script, can be used to store user-defined commands executed during start-up.
Typically, nvramrc is used by a device driver to save start-up configuration variables, to patch device driver code, or to define installation-specific device configuration and device aliases. It can also be used for bug patches or for user-installed extensions. Commands are stored in ASCII, just as the user would type them at the console.
If the use-nvramrc? configuration variable is true, the script is evaluated during the OpenBoot start-up sequence as shown:
• Perform power-on self-test (POST)
• Perform system initialization
• Evaluate the script (if use-nvramrc? is true)
• Execute probe-all (evaluate FCode)
• Execute install-console
• Execute banner
• Execute secondary diagnostics
• Perform default boot (if auto-boot? is true)
It is sometimes desirable to modify the sequence probe-all install-console banner. For example, commands that modify the characteristics of plug-in display devices may need to be executed after the plug-in devices have been probed, but before the console device has been selected. Such commands would need to be executed between probe-all and install-console. Commands that display output on the console would need to be placed after install-console or banner.
This is accomplished by creating a custom script which contains either banner or suppress-banner since the sequence probe-all install-console banner is not executed if either banner or suppress-banner is executed
from the script. This allows the use of probe-all, install-console and banner inside the script, possibly interspersed with other commands, without having those commands re-executed after the script finishes.
Most User Interface commands can be used in the script. The following cannot:
• boot
• go
• nvedit
• password
• reset-all
• setenv security-mode
Editing the Contents of the Script
The script editor, nvedit, lets you create and modify the script using the commands listed in Table 12.
Table 12 Commands Affecting NVRAMAC
Command Description
nvalias alias device-path Stores the command "devalias alias device-path" in the script. The alias persists until either nvunalias or set-defaults is executed.
$nvalias Performs the same function as nvalias except that it takes its arguments, name-string and device-string, from the stack.
nvedit Enters the script editor. If data remains in the temporary buffer from a previous nvedit session, resumes editing those previous contents. If not, reads the contents of nvramrc into the temporary buffer and begins editing it.
nvquit Discards the contents of the temporary buffer, without writing it to nvramrc. Prompts for confirmation.
nvrecover Recovers the contents of nvramrc if they have been lost as a result of the execution of set-defaults; then enters the editor as with nvedit. nvrecover fails if nvedit is executed between the time that the nvramrc contents were lost and the time that nvrecover is executed.
nvrun Executes the contents of the temporary buffer.
nvstore Copies the contents of the temporary buffer to nvramrc; discards the contents of the temporary buffer.
nvunalias alias Deletes the specified alias from nvramrc.
$nvunalias Performs the same function as nvunalias except that it takes its argument, name-string, from the stack.
The editing commands shown in Table 13 are used in the script editor.
Table 13 Script Editor Keystroke Commands
Keystroke Description
Control-B Moves backward one character.
Escape B Moves backward one word.
Control-F Moves forward one character.
Escape F Moves forward one word.
Control-A Moves backward to beginning of the line.
Control-E Moves forward to end of the line.
Control-N Moves to the next line of the script editing buffer.
Control-P Moves to the previous line of the script editing buffer.
Return (Enter) Inserts a new line at the cursor position and advances to the next line.
Control-O Inserts a newline at the cursor position and stays on the current line.
Control-K Erases from the cursor position to the end of the line, storing the erased characters in a save buffer. If at the end of a line, joins the next line to the current line (i.e. deletes the newline).
Delete Erases the previous character.
Backspace Erases the previous character.
Control-H Erases the previous character.
Escape H Erases from beginning of word to just before the cursor, storing erased characters in a save buffer.
Control-W Erases from beginning of word to just before the cursor, storing erased characters in a save buffer.
Control-D Erases the next character.
Escape D Erases from the cursor to the end of the word, storing the erased characters in a save buffer.
Control-U Erases the entire line, storing the erased characters in a save buffer.
Control-Y Inserts the contents of the save buffer before the cursor.
Control-Q Quotes the next character (i.e. allows you to insert control characters).
Control-R Retypes the line.
Control-L Displays the entire contents of the editing buffer.
Control-C Exits the script editor, returning to the OpenBoot command interpreter. The temporary buffer is preserved, but is not written back to the script. (Use nvstore afterwards to write it back.)
Activating the Script
Use the following steps to create and activate the script:
1. At the ok prompt, type nvedit.
Edit the script using editor commands.
2. Type Control-C to get out of the editor and back to the ok prompt.
If you have not yet typed nvstore to save your changes, you may type nvrun to execute the contents of the temporary edit buffer.
3. Type nvstore to save your changes.
4. Enable the interpretation of the script by typing:
setenv use-nvramrc? true
5. Type reset-all to reset the system and execute the script, or type:
nvramrc evaluate
to execute the contents directly.
The following example shows you how to create a simple colon definition in the script.
ok nvedit
0: : hello ( -- )
1: ." Hello, world. " cr
2: ;
3: ^C
ok nvstore
ok setenv use-nvramrc? true
ok reset-all
...
ok hello
Hello, world.
ok
Notice the nvedit line number prompts (0:, 1:, 2:, 3:) in the above example. These prompts are system-dependent.
Hardware Sizing - Oracle Application Server
This document presents a set of guidelines for use when sizing the correct hardware for oracle application server.
The main steps toward sizing the right hardware are the following
1. Analyze the user load and requirement
2. Choose architecture
3. Choose database management system
4. Consider reliability
5. Consider scalability
6. Use Hardware sizing tool
Three types of information will be needed for sizing the hardware:
Processing
The first type of question has to do with processing (i.e., CPU) requirements. The business transaction volumes will be important for sizing CPU requirements. In some situations, this can be reduced to merely asking for “number of users.” In other cases, not all users put the same load on the server, so it may be necessary to ask for the “total number of business transactions processed.” Other questions include: How many orders are entered in a typical 8-hour day? What is the average number of items per order? How many loans are processed? How many hits-per-second are typical for a Web application?
Memory
The second type of question has to do with memory requirements. Often, applications are designed so that separate jobs and/or storage are used for each user. These questions will take the form of: How many order entry users are there? How many accounts payable users are there? How many concurrent users/transactions are there? ...etc.
Disk
The third type of question will have to do with DASD requirements. How many documents and records are there? What is their average size? How many SKUs are maintained? How many customer accounts? How long is historical data kept on-line?
Each of these three categories for information gathering may benefit from additional questions to help determine the complexity or “largeness” of that item. Questions such as
“Are users accessing the application through the Web or a native interface?” might affect the amount of CPU processing.
“What proportion of application users are doing Web browsing versus Web purchasing?” may affect disk activity for updates as compared to the total memory demand for caching frequently referenced Web pages.
Some care must be taken to organize the questions, phrasing them in a logical and comprehensible manner so the end user does not become overwhelmed. Also, keep in mind that code can be provided in the Sizing Guide Solution to offer some reasonable defaults in the event that not all of the information is readily known by the user. In some cases, the customer will only have “impressions” of how the server will be used. This will lead to using a large number of “fuzzy” terms to describe the work. Terms such as “light,” “heavy,” “moderate,” “casual,” and “complex” would be used extensively as answers to the sizing questions. This can make the effort of quantifying the default values more critical to achieving reasonable sizing results.
Sizing Parameters:
The sizing depends heavily on two parameters, 'Total Connected Users' and 'Business Trx/hr for all Users'. Also for light users, 'Business Trx/hr for all users' should be at least 1 to 4 times 'Total Connected Users'. For heavy users, 'Business Trx/hr for all Users' can be upto 12 times the 'Total Connected Users'.
Number of Active Concurrent Users is the number of users who are actively using the system. An active user requests a page, thinks for some time, then requests another page. The user is considered active in the time between the first and last page access, including the think times.
Page View Rate per User is the rate at which the average user generates a page request (i.e. "click") on the system. Isizer expects this number of page views to be expressed in per minute. You can enter a fraction if the rate you desire is less than one.
Number of Hits per Page View Each page view by a user will generate one or more hits on the OC4J server depending on the page and the application behind it due to images and other things in the page. More complex web pages tend to generate more hits and therefore are heavier for OC4J to process.
Workload Type Ultimately sizing OC4J is very dependent on the java application. A poorly written or very complex application will require more resources than a well-written, simple application. We have chosen the Pet Store application to run our benchmarks and generate our sizing metrics. You must estimate how much heavier or lighter your application is compared to Pet Store. A "Browsing" scenario is more appropriate to choose when your web site is mostly used for read only access; more data
A transaction is simply the HTTP hit that primarily constitutes a transaction. Throughput is a measure of the data transferred between users and the application server. Because the test requires all work to be done within an hour, throughput was not an explicit goal of the testing.
Latency is the time it takes one user to perform a transaction and receive results from Application. (Ttransaction latency does not include browser rendering, although it does reflect network load.) Lastly, the term named users represents the total community of users who have login-concurrent users are the authenticated and active subset of named users.
Transaction Concurrency
Transaction concurrency is a derivative of the testing scenario, which simulated users in a typical Application environment with a production database. The testing confirmed that transaction concurrency and latency are directly related. When a system gets busy, then more transactions end up executing at the same time and generally take longer to complete-the level of transaction concurrency increases when latency increases.
Scalability
Scalability refers to the performance characteristics an application as the workload increases, and an the application as it runs on larger and larger server configurations. For example, an application with a characteristic of linear scalability requires twice the server resources to perform twice the workload. Another vertical scalability characteristic involves whether an application can make full use of system resources (e.g., all processors as n-way increases).
The application itself should be “tuned” to make optimal use of CPU, memory, and disk resources that is, to make the application scale in a predictable and efficient manner. Examples of tuning techniques include: analyzing the application’s efficiency, adjusting the application design and implementation to perform as much parallel work in multiple threads (or jobs), and minimizing locking contention between application users (or between various parts of the application). Given enough disk and memory resources, and with enough workload, a highly scalable application can push the processor to 90% utilization or higher.
An application may have been designed for a certain kind of hardware configuration, which effectively means that buying larger, faster hardware may not yield the expected, linear improvement in throughput. For instance, if the application is written to take advantage of 16 threads, then running that application on a 32-way processor will not show throughput that is anywhere near twice as fast.
CPU Sizing
This section includes two formulas for CPU sizing - one for determining a configuration that will provide optimal response times, and one for producing a configuration with good (but less than optimal) response times. In choosing which formula to use, consider the transaction types and user characteristics of the target environment. Section 2, “Test Results” shows which transaction types exhibit better scaling in comparison to others, and this information can be used as a reference to tailor configurations for particular workloads.
The formulas presented below for CPU sizing are based on the number of transactions per CPU. This seems to be the best approach given trends in the test results. Deriving the number of transactions per
CPU requires:
The number of concurrent users, given a named user population of a certain size
The number of concurrent users that have transactions executing at any one point in time Of the total concurrent users, how many would have transactions that are simultaneously executing?
This value is directly related to the transaction latency measured in the tests. For optimal response times, this value is 3.5 percent, and for moderate response times, it is 4.5 percent.
Next, since we know the expected number of transactions in the system, how do these transactions map to CPUs? Again the testing provides some indication-approximately 2.5 transactions were executing on each CPU when response times were optimal, and about 4.5 transactions were executing on each CPU when response times were reasonable (but not optimal).
Total CPU MHz = # Hits/Sec * 4.65
Number of CPUs = Total CPU MHz / MHz per CPU
The main steps toward sizing the right hardware are the following
1. Analyze the user load and requirement
2. Choose architecture
3. Choose database management system
4. Consider reliability
5. Consider scalability
6. Use Hardware sizing tool
Three types of information will be needed for sizing the hardware:
Processing
The first type of question has to do with processing (i.e., CPU) requirements. The business transaction volumes will be important for sizing CPU requirements. In some situations, this can be reduced to merely asking for “number of users.” In other cases, not all users put the same load on the server, so it may be necessary to ask for the “total number of business transactions processed.” Other questions include: How many orders are entered in a typical 8-hour day? What is the average number of items per order? How many loans are processed? How many hits-per-second are typical for a Web application?
Memory
The second type of question has to do with memory requirements. Often, applications are designed so that separate jobs and/or storage are used for each user. These questions will take the form of: How many order entry users are there? How many accounts payable users are there? How many concurrent users/transactions are there? ...etc.
Disk
The third type of question will have to do with DASD requirements. How many documents and records are there? What is their average size? How many SKUs are maintained? How many customer accounts? How long is historical data kept on-line?
Each of these three categories for information gathering may benefit from additional questions to help determine the complexity or “largeness” of that item. Questions such as
“Are users accessing the application through the Web or a native interface?” might affect the amount of CPU processing.
“What proportion of application users are doing Web browsing versus Web purchasing?” may affect disk activity for updates as compared to the total memory demand for caching frequently referenced Web pages.
Some care must be taken to organize the questions, phrasing them in a logical and comprehensible manner so the end user does not become overwhelmed. Also, keep in mind that code can be provided in the Sizing Guide Solution to offer some reasonable defaults in the event that not all of the information is readily known by the user. In some cases, the customer will only have “impressions” of how the server will be used. This will lead to using a large number of “fuzzy” terms to describe the work. Terms such as “light,” “heavy,” “moderate,” “casual,” and “complex” would be used extensively as answers to the sizing questions. This can make the effort of quantifying the default values more critical to achieving reasonable sizing results.
Sizing Parameters:
The sizing depends heavily on two parameters, 'Total Connected Users' and 'Business Trx/hr for all Users'. Also for light users, 'Business Trx/hr for all users' should be at least 1 to 4 times 'Total Connected Users'. For heavy users, 'Business Trx/hr for all Users' can be upto 12 times the 'Total Connected Users'.
Number of Active Concurrent Users is the number of users who are actively using the system. An active user requests a page, thinks for some time, then requests another page. The user is considered active in the time between the first and last page access, including the think times.
Page View Rate per User is the rate at which the average user generates a page request (i.e. "click") on the system. Isizer expects this number of page views to be expressed in per minute. You can enter a fraction if the rate you desire is less than one.
Number of Hits per Page View Each page view by a user will generate one or more hits on the OC4J server depending on the page and the application behind it due to images and other things in the page. More complex web pages tend to generate more hits and therefore are heavier for OC4J to process.
Workload Type Ultimately sizing OC4J is very dependent on the java application. A poorly written or very complex application will require more resources than a well-written, simple application. We have chosen the Pet Store application to run our benchmarks and generate our sizing metrics. You must estimate how much heavier or lighter your application is compared to Pet Store. A "Browsing" scenario is more appropriate to choose when your web site is mostly used for read only access; more data
A transaction is simply the HTTP hit that primarily constitutes a transaction. Throughput is a measure of the data transferred between users and the application server. Because the test requires all work to be done within an hour, throughput was not an explicit goal of the testing.
Latency is the time it takes one user to perform a transaction and receive results from Application. (Ttransaction latency does not include browser rendering, although it does reflect network load.) Lastly, the term named users represents the total community of users who have login-concurrent users are the authenticated and active subset of named users.
Transaction Concurrency
Transaction concurrency is a derivative of the testing scenario, which simulated users in a typical Application environment with a production database. The testing confirmed that transaction concurrency and latency are directly related. When a system gets busy, then more transactions end up executing at the same time and generally take longer to complete-the level of transaction concurrency increases when latency increases.
Scalability
Scalability refers to the performance characteristics an application as the workload increases, and an the application as it runs on larger and larger server configurations. For example, an application with a characteristic of linear scalability requires twice the server resources to perform twice the workload. Another vertical scalability characteristic involves whether an application can make full use of system resources (e.g., all processors as n-way increases).
The application itself should be “tuned” to make optimal use of CPU, memory, and disk resources that is, to make the application scale in a predictable and efficient manner. Examples of tuning techniques include: analyzing the application’s efficiency, adjusting the application design and implementation to perform as much parallel work in multiple threads (or jobs), and minimizing locking contention between application users (or between various parts of the application). Given enough disk and memory resources, and with enough workload, a highly scalable application can push the processor to 90% utilization or higher.
An application may have been designed for a certain kind of hardware configuration, which effectively means that buying larger, faster hardware may not yield the expected, linear improvement in throughput. For instance, if the application is written to take advantage of 16 threads, then running that application on a 32-way processor will not show throughput that is anywhere near twice as fast.
CPU Sizing
This section includes two formulas for CPU sizing - one for determining a configuration that will provide optimal response times, and one for producing a configuration with good (but less than optimal) response times. In choosing which formula to use, consider the transaction types and user characteristics of the target environment. Section 2, “Test Results” shows which transaction types exhibit better scaling in comparison to others, and this information can be used as a reference to tailor configurations for particular workloads.
The formulas presented below for CPU sizing are based on the number of transactions per CPU. This seems to be the best approach given trends in the test results. Deriving the number of transactions per
CPU requires:
The number of concurrent users, given a named user population of a certain size
The number of concurrent users that have transactions executing at any one point in time Of the total concurrent users, how many would have transactions that are simultaneously executing?
This value is directly related to the transaction latency measured in the tests. For optimal response times, this value is 3.5 percent, and for moderate response times, it is 4.5 percent.
Next, since we know the expected number of transactions in the system, how do these transactions map to CPUs? Again the testing provides some indication-approximately 2.5 transactions were executing on each CPU when response times were optimal, and about 4.5 transactions were executing on each CPU when response times were reasonable (but not optimal).
Total CPU MHz = # Hits/Sec * 4.65
Number of CPUs = Total CPU MHz / MHz per CPU
Samba Configuration guide
Introduction
Samba is a useful program to install if your Solaris machine is networked with other machines running Windows. It enables the Solaris system to appear in Network Neighborhood on Windows, thus enabling simple drag-and-drop transfer of files between the systems. Samba also enables the Solaris system to print to printers attached to a Windows system..
Samba is supplied in source form and you need to compile it. This isn't difficult! Before doing so, you need to have installed the g(un)zip program and a C compiler. All of these are freely downloadable from the Net and instructions for installing C and gzip are here.
Installing Samba
1. Download the source code:
The source of Samba is available from http://samba.org. At the time of writing, the latest version is V2.0.6 and the source code is provided as a compressed tar archive in the file samba-2.0.6.tar.gz. Download the file to a temporary directory, such as /tmp.
2. Prepare the source code for compilation:
Make a directory at a convenient point in the file system to hold the source code and copy the source into this directory. For example:
# mkdir -p /opt/source/samba
# cd /opt/source/samba
# cp /tmp/samba-2.0.6.tar.gz .
Unzip and untar the source and then change to the directory created by tar:
# gunzip samba*
# tar xvf samba*
# cd samba-2.0.6
At this point, you may like to have a look at the README file for general information and at the file docs/textdocs/UNIX_INSTALL.txt for detailed installation instructions. If you're impatient, just follow the instructions here which should be enough to get you started..
3. Compile the source code and install Samba:
Configure the compilation process for your system:
# cd source
# ./configure
Compile the source code:
# make
Finally, install the compiled code:
# make install
This installs all the Samba files in directories under /usr/local/samba with the binaries in /usr/local/samba/bin and the manual pages in /usr/local/samba/man.
4. Modify the search path:
You now need to modify the man search path so that the 'man' command can find Samba's manual page. If you're running the CDE windowing system, this is done by editing the file /.dtprofile and adding the following lines (if they aren't already there) to the end of this file:
MANPATH=$MANPATH:/usr/man/:/usr/local/man:/usr/local/samba/man
It's advisable to log out and log in again at this point to activate this change. Make sure that the system can find the Samba manual page:
# man samba
5. Create the Samba lock directory:
At this point, create the lock directory used by Samba:
# mkdir /usr/local/samba/var/locks
6. Create a share directory:
It's useful to create a directory on the Solaris system that is fully shareable on the local network so that Windows systems can read files from the Solaris system and write files to it. To do this:
mkdir /share
chmod 777 /share
chmod +t /share
chown sys /share
chgrp sys share
7. Configure Samba:
Samba is controlled by means of the configuration file /usr/local/samba/lib/smb.conf
Create a basic configuration file containing the following lines:
# Global parameters
workgroup = HOME
security = Share
hosts allow = localhost, local-machine-name, 192.168.1.
hosts deny = All
[root]
path = /
comment = Solaris root
guest ok = Yes
read only = Yes
[share]
path = /share
comment = Solaris share
guest ok = Yes
read only = No
Note that "# Global parameters", "[root]" and "[share]" should be positioned at the start of their lines and all other lines should be prefixed with a tab character.
In this file, replace HOME with the name of your Windows workgroup or domain. On a Windows 95 or 98 system, this is the "Workgroup" name set on the Identification tab in Start -> Settings -> Control Panel -> Network. On NT 4, this name is found in the same place but is called the "Domain".
Also, replace local-machine-name with the name of your Solaris system so that it can connect to the swat Web server described later, and replace 192.168.1 with the first three components of the IP addresses used on your local network. The range 192.168.1.1 to 192.168.1.254 is reserved for private use and is a good choice to use for a local network. Note the presence of a dot after the partial IP address in the configuration file.
The effect of this basic configuration file is to allow access to your Solaris system from Windows machines on the local network only (those with IP addresses starting 192.168.1) and a password is not required to browse the Solaris system. The root file system is shared but is read-only and the /share directory is shared with both read and write access. Incoming connections to the Solaris system have a User and Group identity (uid and gid) of the "nobody" user by default.
This basic configuration file can be amended later, if you wish, to share only specific directories with other networked systems, to require the use of passwords and to allow printing. I recommend that the "swat" program is used (see later) to make further changes to the configuration file.
8. Check the configuration file:
It's advisable to check that Samba is happy with the basic configuration file. Type the following:
# cd /usr/local/samba/bin
# ./testparm
and this should display the following:
Load smb config files from /usr/local/samba/lib/smb.conf
Processing section "[root]"
Processing section "[share]"
Loaded services file OK.
Press enter to see a dump of your service definitions
At this point, press ENTER to see a list of all the default options or type CONTROL and C to exit.
9. Arrange for inetd to start the Samba daemons:
Most of Samba's services are provided by means of three servers or daemons: smbd is the Samba server, nmbd is the NetBIOS name server and swat is a Web-based Samba configuration tool. These deal with incoming connections on ports 137, 139 and 901 respectively and we need to tell the Solaris internet daemon, inetd, to start the appropriate Samba daemons whenever an incoming request is received on these ports.
Edit /etc/services and make the following changes.
Immediately after the line which reads:
sunrpc 111/tcp rpcbind
insert the two lines:
netbios-ns 137/udp # Samba nmbd
netbios-ssn 139/tcp # Samba smbd
and, after the line which reads:
ldaps 636/udp # LDAP protocol over TLS/SSL (was sldap)
insert the line:
swat 901/tcp # Samba swat
Now edit /etc/inetd.conf and add the following three lines to the end of the file:
netbios-ssn stream tcp nowait root /usr/local/samba/bin/smbd smbd
netbios-ns dgram udp wait root /usr/local/samba/bin/nmbd nmbd
swat stream tcp nowait.400 root /usr/local/samba/bin/swat swat
If you have TCP wrappers installed (see Installing and configuring TCP Wrappers on Solaris), the three lines to be added should read:
netbios-ssn stream tcp nowait root /usr/sbin/tcpd /usr/local/samba/bin/smbd smbd
netbios-ns dgram udp wait root /usr/sbin/tcpd /usr/local/samba/bin/nmbd nmbd
swat stream tcp nowait.400 root /usr/sbin/tcpd /usr/local/samba/bin/swat swat
Tell the inetd daemon to re-read its configuration file:
# pkill -HUP inetd
and Samba is installed and working.
10. Simple testing
Start up Windows Explorer on a Windows machine on your local network and look in Network Neighborhood. You should see an entry for your Solaris machine there and you should be able to browse the Solaris file system from the Windows machine. Using standard Windows drag-and-drop techniques, you should be able to copy files (as long as they have global read access) from the Solaris system to the Windows system.. You should also be able to copy files from Windows to directories on Solaris which have global write access, such as /tmp and /share.
11. Using swat
Swat is a Web server which runs on your local machine in response to HTTP connections on port 901. It provides a graphical interface for configuring Samba and access to some of Samba's documentation. To connect to Swat, simply start your Web browser and point it at:
http://localhost:901
If this doesn't work, replace "localhost" with the name of your Solaris machine.
12. And finally:
This page is not intended to be a complete guide to Samba. Its purpose is really to provide a step-by-step guide to installing Samba and making it work without having to plough through the voluminous documentation provided with the software.
If you make further changes to the Samba configuration file smb.conf, note that the two Samba daemons should be told to re-read the file by issuing the commands:
# pkill -HUP smbd
# pkill -HUP nmbd
Start Samba
Smbd –D –s /usr/local/samba/lib/smb.conf
Nmbd –D –s /usr/local/samba/lib/smb.conf
Samba is a useful program to install if your Solaris machine is networked with other machines running Windows. It enables the Solaris system to appear in Network Neighborhood on Windows, thus enabling simple drag-and-drop transfer of files between the systems. Samba also enables the Solaris system to print to printers attached to a Windows system..
Samba is supplied in source form and you need to compile it. This isn't difficult! Before doing so, you need to have installed the g(un)zip program and a C compiler. All of these are freely downloadable from the Net and instructions for installing C and gzip are here.
Installing Samba
1. Download the source code:
The source of Samba is available from http://samba.org. At the time of writing, the latest version is V2.0.6 and the source code is provided as a compressed tar archive in the file samba-2.0.6.tar.gz. Download the file to a temporary directory, such as /tmp.
2. Prepare the source code for compilation:
Make a directory at a convenient point in the file system to hold the source code and copy the source into this directory. For example:
# mkdir -p /opt/source/samba
# cd /opt/source/samba
# cp /tmp/samba-2.0.6.tar.gz .
Unzip and untar the source and then change to the directory created by tar:
# gunzip samba*
# tar xvf samba*
# cd samba-2.0.6
At this point, you may like to have a look at the README file for general information and at the file docs/textdocs/UNIX_INSTALL.txt for detailed installation instructions. If you're impatient, just follow the instructions here which should be enough to get you started..
3. Compile the source code and install Samba:
Configure the compilation process for your system:
# cd source
# ./configure
Compile the source code:
# make
Finally, install the compiled code:
# make install
This installs all the Samba files in directories under /usr/local/samba with the binaries in /usr/local/samba/bin and the manual pages in /usr/local/samba/man.
4. Modify the search path:
You now need to modify the man search path so that the 'man' command can find Samba's manual page. If you're running the CDE windowing system, this is done by editing the file /.dtprofile and adding the following lines (if they aren't already there) to the end of this file:
MANPATH=$MANPATH:/usr/man/:/usr/local/man:/usr/local/samba/man
It's advisable to log out and log in again at this point to activate this change. Make sure that the system can find the Samba manual page:
# man samba
5. Create the Samba lock directory:
At this point, create the lock directory used by Samba:
# mkdir /usr/local/samba/var/locks
6. Create a share directory:
It's useful to create a directory on the Solaris system that is fully shareable on the local network so that Windows systems can read files from the Solaris system and write files to it. To do this:
mkdir /share
chmod 777 /share
chmod +t /share
chown sys /share
chgrp sys share
7. Configure Samba:
Samba is controlled by means of the configuration file /usr/local/samba/lib/smb.conf
Create a basic configuration file containing the following lines:
# Global parameters
workgroup = HOME
security = Share
hosts allow = localhost, local-machine-name, 192.168.1.
hosts deny = All
[root]
path = /
comment = Solaris root
guest ok = Yes
read only = Yes
[share]
path = /share
comment = Solaris share
guest ok = Yes
read only = No
Note that "# Global parameters", "[root]" and "[share]" should be positioned at the start of their lines and all other lines should be prefixed with a tab character.
In this file, replace HOME with the name of your Windows workgroup or domain. On a Windows 95 or 98 system, this is the "Workgroup" name set on the Identification tab in Start -> Settings -> Control Panel -> Network. On NT 4, this name is found in the same place but is called the "Domain".
Also, replace local-machine-name with the name of your Solaris system so that it can connect to the swat Web server described later, and replace 192.168.1 with the first three components of the IP addresses used on your local network. The range 192.168.1.1 to 192.168.1.254 is reserved for private use and is a good choice to use for a local network. Note the presence of a dot after the partial IP address in the configuration file.
The effect of this basic configuration file is to allow access to your Solaris system from Windows machines on the local network only (those with IP addresses starting 192.168.1) and a password is not required to browse the Solaris system. The root file system is shared but is read-only and the /share directory is shared with both read and write access. Incoming connections to the Solaris system have a User and Group identity (uid and gid) of the "nobody" user by default.
This basic configuration file can be amended later, if you wish, to share only specific directories with other networked systems, to require the use of passwords and to allow printing. I recommend that the "swat" program is used (see later) to make further changes to the configuration file.
8. Check the configuration file:
It's advisable to check that Samba is happy with the basic configuration file. Type the following:
# cd /usr/local/samba/bin
# ./testparm
and this should display the following:
Load smb config files from /usr/local/samba/lib/smb.conf
Processing section "[root]"
Processing section "[share]"
Loaded services file OK.
Press enter to see a dump of your service definitions
At this point, press ENTER to see a list of all the default options or type CONTROL and C to exit.
9. Arrange for inetd to start the Samba daemons:
Most of Samba's services are provided by means of three servers or daemons: smbd is the Samba server, nmbd is the NetBIOS name server and swat is a Web-based Samba configuration tool. These deal with incoming connections on ports 137, 139 and 901 respectively and we need to tell the Solaris internet daemon, inetd, to start the appropriate Samba daemons whenever an incoming request is received on these ports.
Edit /etc/services and make the following changes.
Immediately after the line which reads:
sunrpc 111/tcp rpcbind
insert the two lines:
netbios-ns 137/udp # Samba nmbd
netbios-ssn 139/tcp # Samba smbd
and, after the line which reads:
ldaps 636/udp # LDAP protocol over TLS/SSL (was sldap)
insert the line:
swat 901/tcp # Samba swat
Now edit /etc/inetd.conf and add the following three lines to the end of the file:
netbios-ssn stream tcp nowait root /usr/local/samba/bin/smbd smbd
netbios-ns dgram udp wait root /usr/local/samba/bin/nmbd nmbd
swat stream tcp nowait.400 root /usr/local/samba/bin/swat swat
If you have TCP wrappers installed (see Installing and configuring TCP Wrappers on Solaris), the three lines to be added should read:
netbios-ssn stream tcp nowait root /usr/sbin/tcpd /usr/local/samba/bin/smbd smbd
netbios-ns dgram udp wait root /usr/sbin/tcpd /usr/local/samba/bin/nmbd nmbd
swat stream tcp nowait.400 root /usr/sbin/tcpd /usr/local/samba/bin/swat swat
Tell the inetd daemon to re-read its configuration file:
# pkill -HUP inetd
and Samba is installed and working.
10. Simple testing
Start up Windows Explorer on a Windows machine on your local network and look in Network Neighborhood. You should see an entry for your Solaris machine there and you should be able to browse the Solaris file system from the Windows machine. Using standard Windows drag-and-drop techniques, you should be able to copy files (as long as they have global read access) from the Solaris system to the Windows system.. You should also be able to copy files from Windows to directories on Solaris which have global write access, such as /tmp and /share.
11. Using swat
Swat is a Web server which runs on your local machine in response to HTTP connections on port 901. It provides a graphical interface for configuring Samba and access to some of Samba's documentation. To connect to Swat, simply start your Web browser and point it at:
http://localhost:901
If this doesn't work, replace "localhost" with the name of your Solaris machine.
12. And finally:
This page is not intended to be a complete guide to Samba. Its purpose is really to provide a step-by-step guide to installing Samba and making it work without having to plough through the voluminous documentation provided with the software.
If you make further changes to the Samba configuration file smb.conf, note that the two Samba daemons should be told to re-read the file by issuing the commands:
# pkill -HUP smbd
# pkill -HUP nmbd
Start Samba
Smbd –D –s /usr/local/samba/lib/smb.conf
Nmbd –D –s /usr/local/samba/lib/smb.conf
Apache Web server configuration guide
Apache is the most widely used Web server. The below is the configuration guide on unix platform.
Files created by apache
• /etc/httpd/conf/ – This directory contains all the apache configuration files
• /etc/rc.d/ -- This directory contains system startup scripts.
• /var/www – The default documents and web pages.
• /usr/share/man – The man pages for apache.
• /usr/sbin – The executable programs are placed here.
• /var/log/hhtpd – The Server log files are placed here.
Starting and Stopping the Apache Server
Starting
/etc/rc.d/init.d/httpd start
Stoping
/etc/rc.d/init.d/httpd stop
Restarting
/etc/rc.d/init.d/httpd restart
Monitoring the status
/etc/rc.d/init.d/httpd status
Runtime server configuration settings
we have to configure it as per out need. This run time configuration files are
httpd.conf
access.conf
srm.conf
Configuration Directives
• The runtime configuration is done with “Configuration Directives” in the above mentioned files.
• Configuration directives are used the tell the server about various information such as
* Location of files required for server.
* To enable or disable a particular facility.
Syntax for Configuration directive
directive option option ...
• The directives are specified one per line.
Special Directives
• The special directives are also called as “sections”
• The sections are similar to HTML tags
• The contains group of “configuration directives”
Syntax for Special Directives
directive option option
directive option opthin
All special directives are opened with <> tag and closed with tag.
Editing httpd.conf file
Most of the default settings can be left as it is.
The following list provides the directives that are very important.
ServerType Directive
This directive have two options
• Standalone
• inetd
Standalone Directive
Standalone is the most widely used in all web servers, The advantage of using this option is that the client do not have to refer the server for same web page again and again.if a particular web page is being viewed this is being cached by the browser, the user can revisit the page stored in the browser with out intervening the server.
Inetd Directive
Inetd is not widely used, it is slow when compared to standalone option.This option is used for security reason and configuration checking. For each and every request the server spawns its process.
ServerRoot Directive
This directive sets the absolute path to your server directory, It tells where to find all the resources and configuration files.
ServerRoot “/etc/httpd”
By default the server root is set to /etc/httpd directory. If you wish to create a separate configuration in different directory, you can mention that directory.
Port Directive
The Port directive indicates which port your server to run on. By default it is set to 80, which is standard HTTP port number. If you decide to run the server on any other port , the port number can be changed to your desire.
Port 80
User and Group Directives
This directive sets the UID and GID that the server will use to process requests. We should be careful while setting the UID. The UID should be set as a user with no privilege or less privilege.
The default set is
User apache
Group apache
By default the default user and group directive is apache.
ServerAdmin Directive
This should be set to the mail id of the webmaster, if any error occurs it will be mailed to webmasters email id.
ServerAdmin webmaster@drmcet.org
ServerName Directive
The ServerName directive sets the hostname the server will return to client if any request is made.
ServerName www.drmcet.org
DocumentRoot directive
Set it to the absolute path of your document tree. which is the top directory from which apache will serve files.
By default
DocumentRoot “/var/www/html”
If you wish to create your own html source in some other directory you can specify the path of that directory instead of /var/www/html as argument.
In older version of apache this directive is present in srm.conf
UserDir Directive
This directive defines the directory relative to a local user’s home directory where that user can put public HTML documents. It is relative because each user will have their own HTML directory.
The default setting for this directive is public_html. So each user will be able to create a directory called public_html under his home directory.HTML documents available under this directory can be viewed by http://servername/~username, where user name is the name of the particular user.
In older version of apache this directive is present in srm.conf.
UserDir public_html
DirectoryIndex directive
The DirectoryIndex directive indicates which file should be served as the index for a directory,
Multiple files can be specified as index because if any file is not found the next one will be tried.
DirectoryIndex index.html index.htm index.cgi index.shtml
In older version of apache this directive is present in srm.conf
.htaccess File
Almost any directive that appears in the configuration files can appear in an .htaccess file. This file is being called from httpd.conf by “AccessFileName” directive defined as
AccessFileName .htaccess
.htaccess file can override the httpd.conf ‘s configuration. In order to allow and not to allow we can specify a directive called AllowOverride.
An example:
Options Indexes Includes FollowSymLinks
AllowOverride None
Order allow, deny
Allow from all
Options directives
Options can be None, All, or any combination of Indexes, Includes, FollowSymLinks.
None
None of the available options are enabled for this directory.
All
All the available options are enables for this directory.
Indexes
This is an option which search for file options in DirectoryIndex directive.
FollowSymLinks
Allows access to directories that are symbolically linked to a document directory. This is usually a bad idea, and you should not set this for all the directories. You should set it reasonably.
AllowOverrides Directives
The AllowOverrides directives specify which options .htaccess files can override.
Options
The .htaccess file can add options not listed in the Options directive.
FileInfo
The .htaccess file can include directives for modifying document type information.
AuthConfig
The .htaccess file may contain authorization directives.
Limit
The .htaccess file may contain allow, deny, and order directives.
Authentication and Access Control
If you wish that your web site should be viewed only by selected users you can authenticate and authorize the particular user.
Access Restrictions with allow and deny
One of the simplest ways to provide access to a specific group of users is to restrict accesses based on IP address or hostnames. Apache uses allow and deny directives to accomplish this.
Both of these will take an address expression as a parameter.
• All -- can be used to affect all hosts.
• Host or Domain name which can either be a partially or a FQDN
Ex.
sys1.drmcet.org or drmcet.org
• An IP address which can be either full or partial
Ex.
10.10.10 or 10.10.10.25
• A network / Netmask pair such as 10.10.10.0/255.255.255.0
• A network address specified in CIDR format(Classless Internet Domain Routing)
Ex.
10.10.10.0/24
The default behavior of apache is to apply all the Deny directives first and then check the allow directives. If you want to change this order you can use the order statements, There are three different ways in which apache may interpret this statement.
• Order deny, allow – the deny directives are evaluated before allow. If a host is not specifically denied access it will be allowed to access the resource.(This is the default)
• Order allow, deny – all allow directives are evaluated before deny, if a host is not specifically
Allowed access, it will be denied access to the resources.
• Order mutual-failure – only host that are specified in an allow directive and at the same time do not appear in a deny directive will be allowed access.If a host does not appear in either directive it will not be granted access.
Example:
Options Indexes Includes FollowSymLinks
AllowOverride None
Order deny,allow
Allow from drmcet.org
Authentication
Authentication is the process of asking user name and password from the visitor. To get viewed the particular web page the user should have an account in the server.
In order to use a basic authentication you will need a file that lists which users are allowed to access the resources. This file is similar to /etc/passwd file which contains username and encrypted password.
htpasswd Command
To create a user file for Apache, use the htpasswd command. This is included with in the Apache package and it is located at /usr/bin/htpasswd.
To create a new file named “webusers” which will store the user accounts and add a user “user1” to that file , issue the following command
# htpasswd –c webuser user1
here
-c option will create a file named “webuser” .
This –c option should be issued only once while creating the file.
If you intend to add more user to that file just issue the following command
# htpasswd webuser user2
You can also create a groups file which has the following syntax.
Groupname: user1 user2 user3 user4
The first field is the name of the group, the next entries are the member list.
Example:
AuthType Basic
AuthName “Documentation”
AuthUserFile “webusers”
Require vaild-user
Virtual Hosting
One of the most popular service provided with the apache is to host a virtual domain or other wise called as virtual host. This is a complete web site with its own domain name, as if it where a standalone machine, but is is hosted on the same machine as other web sites.
Types of Virtual Hosting
1. Address Based
2. Name Based
Address-Based Virtual Hosts
Configure multiple virtual IP address on the server.
With each IP address you can make independent web sites. By configuring the httpd.conf file as follows.
ServerName www.abc.com
DocumentRoot /home/abc/www
TransferLog /home/abc/log/access_log
ErrorLog /home/abc/log/error_log
ServerName www.mce.com
DocumentRoot /home/mce/www
TransferLog /home/mce/log/access_log
ErrorLog /home/mce/log/error_log
The Directives that cannot be set in VirtualHost sections are as follows.
StartServers, MaxSpareServers, MinSpareServers, MaxRequestsPerChild, BindAddress, Listen, PidFile, TypesConfig, ServerRoot, and NameVirtualHost.
Name-Based Virtual Hosts
Name-based virtual hosts allow you to run more than one host on the same IP address. To accomplish this we have to add additional names to our DNS as CNAMEs(Canonical names).
When an client requests a document from your server, it sends with a request variable indicating the document. Based on this variable, the server determines from which of the virtual hosts it should serve content.
Name base virtual hosts require just one step more than IP address-based virtual hosts. You first need to indicate which IP address has the multiple DNS names on it. This is done with the NameVirtualHost directive.
NameVirtualHost 10.10.10.63
ServerName www.abt.com
DocumentRoot /home/abt/www
TransferLog /home/abt/log/access_log
ErrorLog /home/abt/log/error_log
ServerName www.mcet.com
DocumentRoot /home/mcet/www
TransferLog /home/mcet/log/access_log
ErrorLog /home/mcet/log/error_log
You need to have a section for each name on that address, setting the configuration for the name.
As with IP-based virtual hosts, you only need to set those configurations that need to be different for the host. You must set the ServerName directive because that is the only that distinguish one host from another.
Logging
Apache provides for logging just about any information you might be interested in from web accesses. There are two standard log files that are generated when you run your apache server.
access_log and error_log files. These log files are generated from the CustomLog and LogFormat directives.
Example:
LogFormat “%h %l %u %t \ “%r\” %.s %b” common
The following variables are available for LogFormat statements:
%a Remote IP address
%A Local IP address
%b Bytes sent
%f filename
%h Remote host
%H Request protocol
%l Remote logname
%m Request method
%P Process ID
%t Time
%r First line of request
%s Status
%u the remote user
%U The URL requested
Files created by apache
• /etc/httpd/conf/ – This directory contains all the apache configuration files
• /etc/rc.d/ -- This directory contains system startup scripts.
• /var/www – The default documents and web pages.
• /usr/share/man – The man pages for apache.
• /usr/sbin – The executable programs are placed here.
• /var/log/hhtpd – The Server log files are placed here.
Starting and Stopping the Apache Server
Starting
/etc/rc.d/init.d/httpd start
Stoping
/etc/rc.d/init.d/httpd stop
Restarting
/etc/rc.d/init.d/httpd restart
Monitoring the status
/etc/rc.d/init.d/httpd status
Runtime server configuration settings
we have to configure it as per out need. This run time configuration files are
httpd.conf
access.conf
srm.conf
Configuration Directives
• The runtime configuration is done with “Configuration Directives” in the above mentioned files.
• Configuration directives are used the tell the server about various information such as
* Location of files required for server.
* To enable or disable a particular facility.
Syntax for Configuration directive
directive option option ...
• The directives are specified one per line.
Special Directives
• The special directives are also called as “sections”
• The sections are similar to HTML tags
• The contains group of “configuration directives”
Syntax for Special Directives
directive option option
directive option opthin
All special directives are opened with <> tag and closed with tag.
Editing httpd.conf file
Most of the default settings can be left as it is.
The following list provides the directives that are very important.
ServerType Directive
This directive have two options
• Standalone
• inetd
Standalone Directive
Standalone is the most widely used in all web servers, The advantage of using this option is that the client do not have to refer the server for same web page again and again.if a particular web page is being viewed this is being cached by the browser, the user can revisit the page stored in the browser with out intervening the server.
Inetd Directive
Inetd is not widely used, it is slow when compared to standalone option.This option is used for security reason and configuration checking. For each and every request the server spawns its process.
ServerRoot Directive
This directive sets the absolute path to your server directory, It tells where to find all the resources and configuration files.
ServerRoot “/etc/httpd”
By default the server root is set to /etc/httpd directory. If you wish to create a separate configuration in different directory, you can mention that directory.
Port Directive
The Port directive indicates which port your server to run on. By default it is set to 80, which is standard HTTP port number. If you decide to run the server on any other port , the port number can be changed to your desire.
Port 80
User and Group Directives
This directive sets the UID and GID that the server will use to process requests. We should be careful while setting the UID. The UID should be set as a user with no privilege or less privilege.
The default set is
User apache
Group apache
By default the default user and group directive is apache.
ServerAdmin Directive
This should be set to the mail id of the webmaster, if any error occurs it will be mailed to webmasters email id.
ServerAdmin webmaster@drmcet.org
ServerName Directive
The ServerName directive sets the hostname the server will return to client if any request is made.
ServerName www.drmcet.org
DocumentRoot directive
Set it to the absolute path of your document tree. which is the top directory from which apache will serve files.
By default
DocumentRoot “/var/www/html”
If you wish to create your own html source in some other directory you can specify the path of that directory instead of /var/www/html as argument.
In older version of apache this directive is present in srm.conf
UserDir Directive
This directive defines the directory relative to a local user’s home directory where that user can put public HTML documents. It is relative because each user will have their own HTML directory.
The default setting for this directive is public_html. So each user will be able to create a directory called public_html under his home directory.HTML documents available under this directory can be viewed by http://servername/~username, where user name is the name of the particular user.
In older version of apache this directive is present in srm.conf.
UserDir public_html
DirectoryIndex directive
The DirectoryIndex directive indicates which file should be served as the index for a directory,
Multiple files can be specified as index because if any file is not found the next one will be tried.
DirectoryIndex index.html index.htm index.cgi index.shtml
In older version of apache this directive is present in srm.conf
.htaccess File
Almost any directive that appears in the configuration files can appear in an .htaccess file. This file is being called from httpd.conf by “AccessFileName” directive defined as
AccessFileName .htaccess
.htaccess file can override the httpd.conf ‘s configuration. In order to allow and not to allow we can specify a directive called AllowOverride.
An example:
Options Indexes Includes FollowSymLinks
AllowOverride None
Order allow, deny
Allow from all
Options directives
Options can be None, All, or any combination of Indexes, Includes, FollowSymLinks.
None
None of the available options are enabled for this directory.
All
All the available options are enables for this directory.
Indexes
This is an option which search for file options in DirectoryIndex directive.
FollowSymLinks
Allows access to directories that are symbolically linked to a document directory. This is usually a bad idea, and you should not set this for all the directories. You should set it reasonably.
AllowOverrides Directives
The AllowOverrides directives specify which options .htaccess files can override.
Options
The .htaccess file can add options not listed in the Options directive.
FileInfo
The .htaccess file can include directives for modifying document type information.
AuthConfig
The .htaccess file may contain authorization directives.
Limit
The .htaccess file may contain allow, deny, and order directives.
Authentication and Access Control
If you wish that your web site should be viewed only by selected users you can authenticate and authorize the particular user.
Access Restrictions with allow and deny
One of the simplest ways to provide access to a specific group of users is to restrict accesses based on IP address or hostnames. Apache uses allow and deny directives to accomplish this.
Both of these will take an address expression as a parameter.
• All -- can be used to affect all hosts.
• Host or Domain name which can either be a partially or a FQDN
Ex.
sys1.drmcet.org or drmcet.org
• An IP address which can be either full or partial
Ex.
10.10.10 or 10.10.10.25
• A network / Netmask pair such as 10.10.10.0/255.255.255.0
• A network address specified in CIDR format(Classless Internet Domain Routing)
Ex.
10.10.10.0/24
The default behavior of apache is to apply all the Deny directives first and then check the allow directives. If you want to change this order you can use the order statements, There are three different ways in which apache may interpret this statement.
• Order deny, allow – the deny directives are evaluated before allow. If a host is not specifically denied access it will be allowed to access the resource.(This is the default)
• Order allow, deny – all allow directives are evaluated before deny, if a host is not specifically
Allowed access, it will be denied access to the resources.
• Order mutual-failure – only host that are specified in an allow directive and at the same time do not appear in a deny directive will be allowed access.If a host does not appear in either directive it will not be granted access.
Example:
Options Indexes Includes FollowSymLinks
AllowOverride None
Order deny,allow
Allow from drmcet.org
Authentication
Authentication is the process of asking user name and password from the visitor. To get viewed the particular web page the user should have an account in the server.
In order to use a basic authentication you will need a file that lists which users are allowed to access the resources. This file is similar to /etc/passwd file which contains username and encrypted password.
htpasswd Command
To create a user file for Apache, use the htpasswd command. This is included with in the Apache package and it is located at /usr/bin/htpasswd.
To create a new file named “webusers” which will store the user accounts and add a user “user1” to that file , issue the following command
# htpasswd –c webuser user1
here
-c option will create a file named “webuser” .
This –c option should be issued only once while creating the file.
If you intend to add more user to that file just issue the following command
# htpasswd webuser user2
You can also create a groups file which has the following syntax.
Groupname: user1 user2 user3 user4
The first field is the name of the group, the next entries are the member list.
Example:
AuthType Basic
AuthName “Documentation”
AuthUserFile “webusers”
Require vaild-user
Virtual Hosting
One of the most popular service provided with the apache is to host a virtual domain or other wise called as virtual host. This is a complete web site with its own domain name, as if it where a standalone machine, but is is hosted on the same machine as other web sites.
Types of Virtual Hosting
1. Address Based
2. Name Based
Address-Based Virtual Hosts
Configure multiple virtual IP address on the server.
With each IP address you can make independent web sites. By configuring the httpd.conf file as follows.
ServerName www.abc.com
DocumentRoot /home/abc/www
TransferLog /home/abc/log/access_log
ErrorLog /home/abc/log/error_log
ServerName www.mce.com
DocumentRoot /home/mce/www
TransferLog /home/mce/log/access_log
ErrorLog /home/mce/log/error_log
The Directives that cannot be set in VirtualHost sections are as follows.
StartServers, MaxSpareServers, MinSpareServers, MaxRequestsPerChild, BindAddress, Listen, PidFile, TypesConfig, ServerRoot, and NameVirtualHost.
Name-Based Virtual Hosts
Name-based virtual hosts allow you to run more than one host on the same IP address. To accomplish this we have to add additional names to our DNS as CNAMEs(Canonical names).
When an client requests a document from your server, it sends with a request variable indicating the document. Based on this variable, the server determines from which of the virtual hosts it should serve content.
Name base virtual hosts require just one step more than IP address-based virtual hosts. You first need to indicate which IP address has the multiple DNS names on it. This is done with the NameVirtualHost directive.
NameVirtualHost 10.10.10.63
ServerName www.abt.com
DocumentRoot /home/abt/www
TransferLog /home/abt/log/access_log
ErrorLog /home/abt/log/error_log
ServerName www.mcet.com
DocumentRoot /home/mcet/www
TransferLog /home/mcet/log/access_log
ErrorLog /home/mcet/log/error_log
You need to have a section for each name on that address, setting the configuration for the name.
As with IP-based virtual hosts, you only need to set those configurations that need to be different for the host. You must set the ServerName directive because that is the only that distinguish one host from another.
Logging
Apache provides for logging just about any information you might be interested in from web accesses. There are two standard log files that are generated when you run your apache server.
access_log and error_log files. These log files are generated from the CustomLog and LogFormat directives.
Example:
LogFormat “%h %l %u %t \ “%r\” %.s %b” common
The following variables are available for LogFormat statements:
%a Remote IP address
%A Local IP address
%b Bytes sent
%f filename
%h Remote host
%H Request protocol
%l Remote logname
%m Request method
%P Process ID
%t Time
%r First line of request
%s Status
%u the remote user
%U The URL requested
Tuesday, May 23, 2006
VI COPY FILE TO FILE
Here is how to copy the required number
of lines from one file to another in
VI editor. First use the following
key combinations in the source file.
Press ESCAPE
Press Shift "(Shift double quotes)
Press a
Press the number of lines you want to copy
press y followed by another y
Now press " : " (COLON) to get the vi prompt.
Hit e "Destination file name"
Once you enter the Destination file
go to the line where you want the lines
copied to be inserted.
Press ESCAPE.
Press SHIFT "(Double quotes).
Press a.
Press p.
The lines get copied.
of lines from one file to another in
VI editor. First use the following
key combinations in the source file.
Press ESCAPE
Press Shift "(Shift double quotes)
Press a
Press the number of lines you want to copy
press y followed by another y
Now press " : " (COLON) to get the vi prompt.
Hit e "Destination file name"
Once you enter the Destination file
go to the line where you want the lines
copied to be inserted.
Press ESCAPE.
Press SHIFT "(Double quotes).
Press a.
Press p.
The lines get copied.
Monday, May 22, 2006
Sun Cluster 3.0 Admin command reference
A cluster, or plex, is a collection of loosely coupled computing nodes that provides a single client view of network services or applications, including databases, web services, and file services.
Sun cluster Admin Commands
Start the CCP Launch Pad – ccp cluster name
Interactively configure sun cluster – scsetup
Display the cluster patch number – showrev –p
Displaying sun cluster release and version information – scinstall –pv
Check the status of cluster components – scstat –p
List the cluster configuration information – scconf
View the cluster configuration – scconf –p
Verify the cluster configuration – sccheck
Shutdown the cluster (all nodes) – scshutdown –g0 –y
View the node status – scstat –n
Switch all resource group from one node to another node – scswitch –s –h nodelist
Boot cluster node from OK prompt – boot
Boot the cluster node in non cluster mode – boot –x
Check the status of cluster interconnect - scstat –w
Verify the cluster transport cable – scconf -p | grep cable
Verify the cluster adapter – scconf -p | grep adapter
Verify the cluster Junction – scconf -p | grep junction
Create NAFO (Network Adapter Fail Over )Group - pnmset -c nafo-group - create adapeter adapter
Verify the status of NAFO group – pnmstat –l
Add the adapter to the NAFO group - pnmset –c nafo-group –o add adapter
Identify whether the NAFO group is being used by any logical host or shared address resources – scrgadm –pv
Switch the logical host resource groups and shared address resource groups that
use this NAFO group - scswitch -z -g resource-group -h nodelist
Delete the NAFO group – pnmset –c nafo-group – o delete
Remove the adapter from the NAFO group – pnmset –c nafo-group –o remove adapter
Finding the active adapter in the NAFO group – pnmptor nafo0
Finding Adapter’s NAFO group – pnmrtop qfe0
Public network tunable parameters - /etc/cluster/pnmparams
Changing the cluster name – scconf –c –C cluster=clustername
Prevent new machine from being added to the cluster – scconf –a –T node=.
This will enable all the new machine to be added to the cluster – scconf –r –T all
Set date on ok prompt – date HHMMSS
Sync date with remote host – rdate hostname
Put node in Maintenance mode – scconf -c –q node=node, maintstate
Verify the cluster node state – scstat –q
Bring a cluster node out of maintenance mode - scconf –c –q node=node,reset
Shutdown the cluster – scshutdown -y –g0 grace period “ message”
Sun cluster Admin Commands
Start the CCP Launch Pad – ccp cluster name
Interactively configure sun cluster – scsetup
Display the cluster patch number – showrev –p
Displaying sun cluster release and version information – scinstall –pv
Check the status of cluster components – scstat –p
List the cluster configuration information – scconf
View the cluster configuration – scconf –p
Verify the cluster configuration – sccheck
Shutdown the cluster (all nodes) – scshutdown –g0 –y
View the node status – scstat –n
Switch all resource group from one node to another node – scswitch –s –h nodelist
Boot cluster node from OK prompt – boot
Boot the cluster node in non cluster mode – boot –x
Check the status of cluster interconnect - scstat –w
Verify the cluster transport cable – scconf -p | grep cable
Verify the cluster adapter – scconf -p | grep adapter
Verify the cluster Junction – scconf -p | grep junction
Create NAFO (Network Adapter Fail Over )Group - pnmset -c nafo-group - create adapeter adapter
Verify the status of NAFO group – pnmstat –l
Add the adapter to the NAFO group - pnmset –c nafo-group –o add adapter
Identify whether the NAFO group is being used by any logical host or shared address resources – scrgadm –pv
Switch the logical host resource groups and shared address resource groups that
use this NAFO group - scswitch -z -g resource-group -h nodelist
Delete the NAFO group – pnmset –c nafo-group – o delete
Remove the adapter from the NAFO group – pnmset –c nafo-group –o remove adapter
Finding the active adapter in the NAFO group – pnmptor nafo0
Finding Adapter’s NAFO group – pnmrtop qfe0
Public network tunable parameters - /etc/cluster/pnmparams
Changing the cluster name – scconf –c –C cluster=clustername
Prevent new machine from being added to the cluster – scconf –a –T node=.
This will enable all the new machine to be added to the cluster – scconf –r –T all
Set date on ok prompt – date HHMMSS
Sync date with remote host – rdate hostname
Put node in Maintenance mode – scconf -c –q node=node, maintstate
Verify the cluster node state – scstat –q
Bring a cluster node out of maintenance mode - scconf –c –q node=node,reset
Shutdown the cluster – scshutdown -y –g0 grace period “ message”
Sunday, May 21, 2006
Solaris Patch Administration
A patch is a collection of files intended to update or fix problems with installed software. For example, a patch might be required to fix a problem with a system command or address a security issue. Because most system and application software are installed as packages, patches are applied against one or more packages.
Actually, patches are special packages used to update other packages. Like packages, a collection of patches can be grouped together into a patch cluster.
The ability to obtain and install patches, keep track of installed patches, and occasionally remove patches are key skills of a competent system administrator.
Obtaining Patches and Patch Information
You can obtain patches from Sun Microsystems in several ways. The two most common methods are purchasing a service contract from Sun or downloading the patches yourself from Sun's Web or FTP site.
Sun Service customers have access to an online patch database and an extended set of patches. The patches can be downloaded from Sun's Web site or FTP site. In addition, Sun Service customers receive a CD-ROM of patches every six to eight weeks.
Everyone else can obtain recommended and security patches for supported systems on the Web at http://sunsolve.sun.com or through anonymous FTP from ftp://sunsolve1.sun.com/pubs/patches.
Sun offers a bimonthly report that summarizes recommended and security patches for each supported system. Like the patches, the information is available at http://sunsolve.sun.com along with other system support information.
Patches are identified with an eight-digit number. The first six digits identify the base patch, and the last two digits identify the revision. For example, patch number 110906-01 is the update for the x86 version of the Solaris 8 find(1) command.
Installing a Patch
You install patches by using the patchadd command. The appropriate type of system configuration must be specified by using a patchadd command-line argument. You might also need to specify a target directory. In addition, you can use a single patchadd command to install more than one patch.
Regardless of the type of system configuration being patched, the patchadd command is typically executed locally on the system where the software being patched resides (the target directory). However, you can install patches remotely over the network if the target directory can be accessed through Network File System (NFS) services.
If the patch is on a CD-ROM, you can install it directly from the CD-ROM. A patch downloaded from the Sun Web or FTP site must reside on a system hard disk. The area where patches are stored before they are installed is referred to as the spool directory.
Although patches have no required spool directory, the most commonly used location is the /var/spool/patch directory. However, you can use any location on the system that has adequate free space.
If a patch was obtained via download, chances are good that it is zipped (compressed) to make it easier and quicker to download. Some patches (mainly for SPARC platforms) are compressed with the gzip(1) command and have filenames ending with the .gz suffix. Others are compressed with the zip(1) command and have filenames ending with the .zip suffix. The zip command is used for both SPARC and Intel x86 platforms. To uncompress or unzip the x86 find patch (110906-01), which is located in the current directory, use the unzip(1) command as shown in the following
example:
# unzip 110906-01.zip
Archive: 110906-01.zip
creating: 110906-01/
inflating: 110906-01/.diPatch
creating: 110906-01/SUNWcsu/
inflating: 110906-01/SUNWcsu/pkgmap
inflating: 110906-01/SUNWcsu/pkginfo
creating: 110906-01/SUNWcsu/install/
inflating: 110906-01/SUNWcsu/install/checkinstall
inflating: 110906-01/SUNWcsu/install/copyright
inflating: 110906-01/SUNWcsu/install/i.none
inflating: 110906-01/SUNWcsu/install/patch_checkinstall
inflating: 110906-01/SUNWcsu/install/patch_postinstall
inflating: 110906-01/SUNWcsu/install/postinstall
inflating: 110906-01/SUNWcsu/install/preinstall
creating: 110906-01/SUNWcsu/reloc/
creating: 110906-01/SUNWcsu/reloc/usr/
creating: 110906-01/SUNWcsu/reloc/usr/bin/
inflating: 110906-01/SUNWcsu/reloc/usr/bin/find
inflating: 110906-01/README.110906-01
#
A subdirectory with the same name as the patch will be created under the current directory, and the unzipped files will be placed in this subdirectory.
You then use the patchadd command to install the patch. Because patches have no default spool directory, you must specify the full pathname to the patch as a command-line argument. The following example shows the installation of the x86 find command patch on a standalone system:
# patchadd 110906-01
Checking installed patches...
Verifying sufficient filesystem capacity (dry run method)...
Installing patch packages...
Patch number 110906-01 has been successfully installed.
See /var/sadm/patch/110906-01/log for details
Patch packages installed:
SUNWcsu
#
Note that the patch modified the SUNWcsu package (core Solaris software). The patchadd command is actually a ksh script that calls the pkgadd command to install the patch.
To apply a patch to the bootable root image of a diskless client or AutoClient, use the -R command-line argument and specify the path to the client's root image. For example, applying the Solaris 8 x86 find command patch to a diskless client that uses a root image stored under the /export/root/client directory on the current system requires the following command:
patchadd -R /export/root/client /var/spool/patch/110906-01
To apply a patch to an operating system (OS) service, use the -S command-line argument and specify the service. (See Chapter 13, "The Solaris Network Environment," for information about OS servers.) For example, applying the Solaris 8 find command patch to an x86 Solaris 8 OS service named Solaris_8x86 on the OS server requires the following command:
patchadd -S Solaris_8x86 /var/spool/patch/110906-01
To apply a patch to the mini root of a net install image (the image used to install a system over the network), use the -C command-line argument and specify the pathname to the net install image. For example, applying the Solaris 8 find command patch to an x86 Solaris 8 image on the Solaris_8x86 net install server requires the following command:
patchadd -C /export/Solaris_8x86/Tools/Boot
/var/spool/patch/110906-01
Multiple patches can be installed by using the patchadd command with the -M command-line argument and by specifying a directory where all the patches are located and a list of the patch numbers. For example, to install patches 108529-05, 108653-23, and 108876-07, which are all located in the /var/spool/patch directory, you can use the following command:
patchadd -M /var/spool/patch 108529-05 108653-23 108876-07
Instead of listing several patches on the command line, you can create a text file containing a list of patches. Then specify the name of the text file on the command line in place of all the individual patch names.
For example, to install the 108529-05, 108653-23, and 108876-07 patches located in the /var/spool/patch directory, create a text file with the name /var/spool/patch/patchlist that contains the name of the three patches (separated by spaces or returns). Then use the following command to install the patches:
patchadd -M /var/spool/patch /var/spool/patch/patchlist
The -M command-line argument can be used to install multiple patches for client, services, or install servers by specifying the previously described -R, -S, or -C command-line argument. This argument should be specified after the -M patch spool directory and patch names or patch list command-line arguments. See the previous examples of the patchadd command for use of these arguments.
By default, any files that will be changed as a result of the patch's installation are copied to one or more backup directories. If necessary, you can then remove the patch and return the system to its state before the patch was installed. However, if you specify the -d command-line argument on the patchadd command, the files are not backed up, and the patch cannot be removed.
The default backup directories, located under /var/sadm/pkg, are based on the installed package or packages being modified by the patch and the patch number. For example, the x86 find command patch (110906-01) modified the SUNWcsu package. Any files changed by installing this patch will be saved under the /var/sadm/pkg/SUNWcsu/110906-01 directory. You can specify a different backup directory by using the -B command-line argument.
The patchadd command will fail if any of the following occur:
• A package being patched is not installed or is only partially installed.
• The patch requires another patch that is not installed.
• The patch is incompatible with another patch already installed.
• The current version or a higher version of the patch is already installed.
• The architecture of the patch and the system do not match.
After you unzip a patch, you can delete the zip file to save space. Likewise, after you install a patch, you can delete the files associated with the patch in the patch spool directory to save space.
Determining Which Patches Are Installed
Two commands can be used to generate a list of installed patches for a standalone system:
• showrev -p
• patchadd -p
Both commands generate almost identical lists. The following example illustrates the use of the showrev(1M) command (the output is formatted for readability):
$ showrev -p
Patch: 110906-01
Obsoletes:
Requires:
Incompatibles:
Packages: SUNWcsu
Patch: 108632-06
Obsoletes:
Requires: 109000-01, 109038-01, 109067-02, 108994-01, 108969-01
Incompatibles:
Packages: SUNWcsr, SUNWnisr, SUNWncar
$
When a patch is installed, information about the patch is added to the pkginfo file of each package the patch updates. The pkginfo files are located in subdirectories under the /var/sadm/pkg directory. The showrev and patchadd commands extract and format information from the pkginfo files. In addition to the patch number and packages the patch updates, the commands list any dependency information, such as other required patches or incompatible patches.
You can use the patchadd command to display a list of installed patches for other system configurations by using the -C, -R, and -S command-line arguments, as previously described. For example, to display the patches applied to an OS service named Solaris8x86, you can use the following patchadd command:
patchadd -S solaris8x86 -p
To display a list of patches applied to a particular package, use the pkgparam command. The following example lists the patches applied to the SUNWcsu package:
$ pkgparam SUNWcsu PATCHLIST
108529-01 108826-01 108900-01 108980-04 108986-01 108990-02
109010-01 109020-01 109028-01 109044-02 109046-02 109092-01
109138-01 109146-01 109148-01 109150-01 109278-01 108965-02
108976-02 109004-01 109006-01 109008-01 109012-01 109016-01
109018-01 109022-01 109024-01 109032-01
109034-01 109036-01
110906-01
$
Removing a Patch
The patchrm command is used to remove or back out a patch by specifying the patch number as a command-line argument. This command also supports the system configurations that the patchadd command supports. You use the same -C, -R, and -S command-line arguments, as previously described. For example, to remove patch 110906-01 from the bootable root image of a diskless client named client5, you can use the following patchrm command:
patchrm -R /export/root/client5 110906-01
Because the default backup directory could have been changed during installation by using the -B command-line argument to the patchadd command, the patchrm command also supports the -B argument. In addition, you can force the patchrm command to remove a patch that has been superseded by another patch by using the -f command-line argument.
You can remove installed patches and return the system to the state it was in before the patch was installed as long as the following conditions are met:
• The patch is not required by another patch or has been made obsolete by a later patch.
• The patch was not installed by using patchadd -d, which instructs patchadd not to save a copy of files before they are updated or replaced.
Actually, patches are special packages used to update other packages. Like packages, a collection of patches can be grouped together into a patch cluster.
The ability to obtain and install patches, keep track of installed patches, and occasionally remove patches are key skills of a competent system administrator.
Obtaining Patches and Patch Information
You can obtain patches from Sun Microsystems in several ways. The two most common methods are purchasing a service contract from Sun or downloading the patches yourself from Sun's Web or FTP site.
Sun Service customers have access to an online patch database and an extended set of patches. The patches can be downloaded from Sun's Web site or FTP site. In addition, Sun Service customers receive a CD-ROM of patches every six to eight weeks.
Everyone else can obtain recommended and security patches for supported systems on the Web at http://sunsolve.sun.com or through anonymous FTP from ftp://sunsolve1.sun.com/pubs/patches.
Sun offers a bimonthly report that summarizes recommended and security patches for each supported system. Like the patches, the information is available at http://sunsolve.sun.com along with other system support information.
Patches are identified with an eight-digit number. The first six digits identify the base patch, and the last two digits identify the revision. For example, patch number 110906-01 is the update for the x86 version of the Solaris 8 find(1) command.
Installing a Patch
You install patches by using the patchadd command. The appropriate type of system configuration must be specified by using a patchadd command-line argument. You might also need to specify a target directory. In addition, you can use a single patchadd command to install more than one patch.
Regardless of the type of system configuration being patched, the patchadd command is typically executed locally on the system where the software being patched resides (the target directory). However, you can install patches remotely over the network if the target directory can be accessed through Network File System (NFS) services.
If the patch is on a CD-ROM, you can install it directly from the CD-ROM. A patch downloaded from the Sun Web or FTP site must reside on a system hard disk. The area where patches are stored before they are installed is referred to as the spool directory.
Although patches have no required spool directory, the most commonly used location is the /var/spool/patch directory. However, you can use any location on the system that has adequate free space.
If a patch was obtained via download, chances are good that it is zipped (compressed) to make it easier and quicker to download. Some patches (mainly for SPARC platforms) are compressed with the gzip(1) command and have filenames ending with the .gz suffix. Others are compressed with the zip(1) command and have filenames ending with the .zip suffix. The zip command is used for both SPARC and Intel x86 platforms. To uncompress or unzip the x86 find patch (110906-01), which is located in the current directory, use the unzip(1) command as shown in the following
example:
# unzip 110906-01.zip
Archive: 110906-01.zip
creating: 110906-01/
inflating: 110906-01/.diPatch
creating: 110906-01/SUNWcsu/
inflating: 110906-01/SUNWcsu/pkgmap
inflating: 110906-01/SUNWcsu/pkginfo
creating: 110906-01/SUNWcsu/install/
inflating: 110906-01/SUNWcsu/install/checkinstall
inflating: 110906-01/SUNWcsu/install/copyright
inflating: 110906-01/SUNWcsu/install/i.none
inflating: 110906-01/SUNWcsu/install/patch_checkinstall
inflating: 110906-01/SUNWcsu/install/patch_postinstall
inflating: 110906-01/SUNWcsu/install/postinstall
inflating: 110906-01/SUNWcsu/install/preinstall
creating: 110906-01/SUNWcsu/reloc/
creating: 110906-01/SUNWcsu/reloc/usr/
creating: 110906-01/SUNWcsu/reloc/usr/bin/
inflating: 110906-01/SUNWcsu/reloc/usr/bin/find
inflating: 110906-01/README.110906-01
#
A subdirectory with the same name as the patch will be created under the current directory, and the unzipped files will be placed in this subdirectory.
You then use the patchadd command to install the patch. Because patches have no default spool directory, you must specify the full pathname to the patch as a command-line argument. The following example shows the installation of the x86 find command patch on a standalone system:
# patchadd 110906-01
Checking installed patches...
Verifying sufficient filesystem capacity (dry run method)...
Installing patch packages...
Patch number 110906-01 has been successfully installed.
See /var/sadm/patch/110906-01/log for details
Patch packages installed:
SUNWcsu
#
Note that the patch modified the SUNWcsu package (core Solaris software). The patchadd command is actually a ksh script that calls the pkgadd command to install the patch.
To apply a patch to the bootable root image of a diskless client or AutoClient, use the -R command-line argument and specify the path to the client's root image. For example, applying the Solaris 8 x86 find command patch to a diskless client that uses a root image stored under the /export/root/client directory on the current system requires the following command:
patchadd -R /export/root/client /var/spool/patch/110906-01
To apply a patch to an operating system (OS) service, use the -S command-line argument and specify the service. (See Chapter 13, "The Solaris Network Environment," for information about OS servers.) For example, applying the Solaris 8 find command patch to an x86 Solaris 8 OS service named Solaris_8x86 on the OS server requires the following command:
patchadd -S Solaris_8x86 /var/spool/patch/110906-01
To apply a patch to the mini root of a net install image (the image used to install a system over the network), use the -C command-line argument and specify the pathname to the net install image. For example, applying the Solaris 8 find command patch to an x86 Solaris 8 image on the Solaris_8x86 net install server requires the following command:
patchadd -C /export/Solaris_8x86/Tools/Boot
/var/spool/patch/110906-01
Multiple patches can be installed by using the patchadd command with the -M command-line argument and by specifying a directory where all the patches are located and a list of the patch numbers. For example, to install patches 108529-05, 108653-23, and 108876-07, which are all located in the /var/spool/patch directory, you can use the following command:
patchadd -M /var/spool/patch 108529-05 108653-23 108876-07
Instead of listing several patches on the command line, you can create a text file containing a list of patches. Then specify the name of the text file on the command line in place of all the individual patch names.
For example, to install the 108529-05, 108653-23, and 108876-07 patches located in the /var/spool/patch directory, create a text file with the name /var/spool/patch/patchlist that contains the name of the three patches (separated by spaces or returns). Then use the following command to install the patches:
patchadd -M /var/spool/patch /var/spool/patch/patchlist
The -M command-line argument can be used to install multiple patches for client, services, or install servers by specifying the previously described -R, -S, or -C command-line argument. This argument should be specified after the -M patch spool directory and patch names or patch list command-line arguments. See the previous examples of the patchadd command for use of these arguments.
By default, any files that will be changed as a result of the patch's installation are copied to one or more backup directories. If necessary, you can then remove the patch and return the system to its state before the patch was installed. However, if you specify the -d command-line argument on the patchadd command, the files are not backed up, and the patch cannot be removed.
The default backup directories, located under /var/sadm/pkg, are based on the installed package or packages being modified by the patch and the patch number. For example, the x86 find command patch (110906-01) modified the SUNWcsu package. Any files changed by installing this patch will be saved under the /var/sadm/pkg/SUNWcsu/110906-01 directory. You can specify a different backup directory by using the -B command-line argument.
The patchadd command will fail if any of the following occur:
• A package being patched is not installed or is only partially installed.
• The patch requires another patch that is not installed.
• The patch is incompatible with another patch already installed.
• The current version or a higher version of the patch is already installed.
• The architecture of the patch and the system do not match.
After you unzip a patch, you can delete the zip file to save space. Likewise, after you install a patch, you can delete the files associated with the patch in the patch spool directory to save space.
Determining Which Patches Are Installed
Two commands can be used to generate a list of installed patches for a standalone system:
• showrev -p
• patchadd -p
Both commands generate almost identical lists. The following example illustrates the use of the showrev(1M) command (the output is formatted for readability):
$ showrev -p
Patch: 110906-01
Obsoletes:
Requires:
Incompatibles:
Packages: SUNWcsu
Patch: 108632-06
Obsoletes:
Requires: 109000-01, 109038-01, 109067-02, 108994-01, 108969-01
Incompatibles:
Packages: SUNWcsr, SUNWnisr, SUNWncar
$
When a patch is installed, information about the patch is added to the pkginfo file of each package the patch updates. The pkginfo files are located in subdirectories under the /var/sadm/pkg directory. The showrev and patchadd commands extract and format information from the pkginfo files. In addition to the patch number and packages the patch updates, the commands list any dependency information, such as other required patches or incompatible patches.
You can use the patchadd command to display a list of installed patches for other system configurations by using the -C, -R, and -S command-line arguments, as previously described. For example, to display the patches applied to an OS service named Solaris8x86, you can use the following patchadd command:
patchadd -S solaris8x86 -p
To display a list of patches applied to a particular package, use the pkgparam command. The following example lists the patches applied to the SUNWcsu package:
$ pkgparam SUNWcsu PATCHLIST
108529-01 108826-01 108900-01 108980-04 108986-01 108990-02
109010-01 109020-01 109028-01 109044-02 109046-02 109092-01
109138-01 109146-01 109148-01 109150-01 109278-01 108965-02
108976-02 109004-01 109006-01 109008-01 109012-01 109016-01
109018-01 109022-01 109024-01 109032-01
109034-01 109036-01
110906-01
$
Removing a Patch
The patchrm command is used to remove or back out a patch by specifying the patch number as a command-line argument. This command also supports the system configurations that the patchadd command supports. You use the same -C, -R, and -S command-line arguments, as previously described. For example, to remove patch 110906-01 from the bootable root image of a diskless client named client5, you can use the following patchrm command:
patchrm -R /export/root/client5 110906-01
Because the default backup directory could have been changed during installation by using the -B command-line argument to the patchadd command, the patchrm command also supports the -B argument. In addition, you can force the patchrm command to remove a patch that has been superseded by another patch by using the -f command-line argument.
You can remove installed patches and return the system to the state it was in before the patch was installed as long as the following conditions are met:
• The patch is not required by another patch or has been made obsolete by a later patch.
• The patch was not installed by using patchadd -d, which instructs patchadd not to save a copy of files before they are updated or replaced.
