7 Documentation Notes

This chapter contains release notes that apply to DIGITAL UNIX Version 4.0D documentation. It discusses the following topics:

7.1 Documentation Overview

The online version of the Documentation Overview, Glossary, and Master Index has been changed in the following ways for this release:

It has been divided into two separate books: Documentation Overview and Glossary and Master Index.
Information in the Documentation Overview has been reorganized and expanded to provide a more comprehensive view of the DIGITAL UNIX documentation set and other information of importance to users of the DIGITAL UNIX operating system.

Because only the online version has changed, that version differs substantially from the printed version.

Also, the Master Index was not revised for this release; therefore, some of the index entries for books that have been revised since the Version 4.0 release may be inaccurate.

A new printed version of the Documentation Overview will be offered with the next major release of DIGITAL UNIX. At that time, the Glossary and Master Index will also be updated and provided as a separate book in both online and printed versions.

7.2 Network Administration Guide

The following sections describe changes to the Network Administration manual.

7.2.1 Section 4.2.2.2 (Verifying PPP Support in the Kernel) Is Obsolete

The following instructions replace the instructions in Section 4.2.2.2:

To verify that PPP is supported in the kernel, enter the following command:

# sysconfig -s | grep ppp

If it is not loaded and configured, do the following:

Log in as root.
Save the /vmunix file.
Rebuild the kernel by running the doconfig program and selecting the Point-to-Point Protocol (PPP) option.
Copy the new vmunix file to /vmunix.
Add the following entry to the /etc/sysconfigtab file using the sysconfigdb utility:
```
ppp:
nppp=2
```
This provides for 2 PPP connections. If your system requires a greater number of PPP connections, increase the number.
Reboot the system.

7.2.2 Sections 4.2.3.1, 4.2.3.2, and 4.2.3.3 Are Obsolete

The following instructions replace the instructions in Sections 4.2.3.1, 4.2.3.2, and 4.2.3.3:

7.2.2.1 Establishing a PPP Dial-Out Connection

After you have connected your modem to a serial port on your system, or installed a supported modem card option, do the following:

Verify that you can communicate with the modem. Do the following:
1. Edit the /etc/remote file and copy the kdebug entry.
2. Modify the new entry, providing a system name for the entry, the correct DIGITAL UNIX device (tty00 or tty01 depending on your system), the correct baud rate, and correct parity. See the remote(4) reference page for more information.
3. Use the tip command to access the modem as follows:
  % tip system_name
  
  system_name is the system name from the /etc/remote file.
4. If your modem is using the AT command language, enter the following command:
```
AT[Return]
```
  If the modem is not in quiet mode, it responds with an OK message.
Contact the remote system administrator or your internet service provider (ISP) and obtain the following information:
- Your remote IP address and netmask, unless the remote system assigns the IP address dynamically
- Characters that might need to be escaped
- Instructions on how to log in and use the remote service
This information is used to create a chat script, which automates the dial-out process.
Create a file for commands that the chat program uses to direct the modem what number to dial and what to send the remote system in order to start pppd. This file is called a chat script. Each entry in a chat script has the following format:
string_chat_expects string_chat_sends

For example, the following file, named /etc/ppp/chat-script, contains the following information:
```
 atdt2135476    [1]
CONNECT     [2]
login: myname      [3]
Password: "\qmypassword"    [4]
"$ " "\qpppd"       [5]
```
1. The chat script expects nothing and sends a dial command to the modem. [Return to example]
2. The chat script expects a CONNECT message and sends a carriage return (implied). [Return to example]
3. The chat script expects the login: string and sends the myname string. [Return to example]
4. The chat script expects the Password: string and sends the mypassword string. The /eq escape sequence prevents chat from logging the password when you use the -v option. [Return to example]
5. The chat script expects the $ (the shell prompt) and sends pppd to start the pppd daemon on the remote machine. The \q escape sequence cancels the effect of the previous \q. [Return to example]
See the chat(8) reference page for more information on chat and chat scripts.
Note
You might want to use the tip command to dial out and log in to the remote system and to write down the exact prompt, login sequence, and pppd start-up sequence.
Edit the /etc/ppp/options file and include the following pppd options as required by the remote system or ISP:
```
defaultroute   [1]
asyncmap 0  [2]
mru 296 [3]
netmask dd.dd.dd.dd  [4]
lcp-echo-interval 60  [5]
lcp-echo-failure 5   [6]
noipdefault  [7]
crtscts  [8]
debug  [9]
```
If your system is a standalone and you are connecting to the Internet through the remote system, add a default route via the remote host by specifying this option. [Return to example] If the serial line is not completely 8-bit transparent, specify this option; asyncmap 200a0000 is appropriate if the serial link includes a telnet link. [Return to example] Reduces the maximum receive unit (MRU) on the local and remote systems to improve performance for multiple IP connections. [Return to example] Sets the interface netmask to the specified value. Your ISP should provide this information. [Return to example] Sends a Link Control Protocol (LCP) echo request frame to the remote system every 60 seconds. This determines whether the link to the remote system is still active. [Return to example] If the local system does not receive a response from the remote system after five LCP echo request frames, pppd considers the link dead and tears down the connection. [Return to example] Specifies that the remote system (ISP) is to provide an IP address to the local system, unless an IP address is specified explicitly on the command line or in an options file. [Return to example] Enables hardware flow control on the serial device. If the modem does not support hardware flow control, do not add this entry. See your modem documentation to verify this information. [Return to example] Enables debugging. All log messages are sent to the file specified in the /etc/syslog.conf file. After your connection is working correctly, remove this entry from the PPP options file. [Return to example] See the pppd(8) reference page for a complete list of pppd options.
Edit the /etc/syslog.conf file and do the following: Add the local2 facility (used by pppd and chat) to the line that specifies /dev/console as the message destination, as follows: kern.debug;local2.notice /dev/console In this example, the notice level is specified. Add the following entry to the file to create a ppp-log file: local2.debug /etc/ppp/ppp-log Save the edits and close the file.
Stop and restart syslogd by entering the following commands: # /sbin/init.d/syslog stop # /sbin/init.d/syslog start
Invoke pppd on the local system to connect to the remote system. For example, the following command starts a link on tty01 and specifies the connect option to run the chat program and the specified chat script file. % pppd /dev/tty01 38400 connect 'chat -v -f /etc/ppp/chat-script'
Issue the following command to monitor the ppp-log file and to determine whether the PPP connection is active: % tail -f /etc/ppp/ppp-log

If any problems occur while using PPP, see Chapter 13 in Network Administration.



7.2.2.2    Establishing a PPP Dial-In Connection


After you have connected your modem to a serial port on your system, to
configure a dial-in system, complete the following steps:



Set up your modem for dial-in access.  See Section 4.3.2 in
Network Administration
for more information.

Edit the /etc/passwd file and create a dedicated entry for a PPP user. For the login shell field, specify /usr/sbin/startppp; for example:
```
ppp1:password:10:20:Remote PPP User:/usr/users/guest:/usr/sbin/startppp
```
Edit the /etc/inittab file and create an entry for each terminal device that is to run PPP. For example: modem:3:respawn:/usr/sbin/getty /dev/tty00 M38400 vt100 See the inittab(4) reference page for more information.
Issue the init q command to start the getty process immediately.
If the dial-in system is going to be a gateway for the dial-out system to reach other systems on the LAN, the dial-in system must be configured as an IP router and must also run gated. Edit the /etc/gated.conf file and delete the nobroadcast option (if specified) in the rip statement. See Chapter 2 of Network Administration for basic network setup information and the gated.conf(4) reference page for gated options.
Edit the /etc/ppp/options file and include the following pppd options required to support dial-in access for all remote users:
```
netmask dd.dd.dd.dd  [1]
proxyarp  [2]
crtscts  [3]
asyncmap 0  [4]
:remote_ip_address  [5]
debug  [6]
```
Sets the interface netmask to the specified value. [Return to example] Adds an entry to the local system's Address Resolution Protocol (ARP) table that contains the IP address of the remote system and the Ethernet address of the local system. This is not necessary if gated is running. [Return to example] Enables hardware flow control for the serial port. [Return to example] If the serial line is not completely 8-bit transparent, specify this option; asyncmap 200a0000 is appropriate if the serial link includes a telnet link. [Return to example] Specifies an IP address for the remote system. [Return to example] If you want to specify options for each individual serial port, create a /etc/ppp/options.ttyxx file and include the remote IP address and any other options that apply to that specific serial port. See the pppd(8) reference page for a complete list of pppd options.
After an incoming call is received and a connection established, startppp runs in the background. The process ID is logged in the /etc/ppp/pppxx.pid file.
Enables debugging. All log messages are sent to the file specified in the /etc/syslog.conf file. After your connection is working correctly, remove this entry from the PPP options file.

If any problems occur while using PPP, see Chapter 13 in Network Administration.



7.3    System Administration Guide


The following notes describe changes to the
System Administration
guide.











7.3.1    Hard Limit for File System Quotas





In the
System Administration
guide, file system hard and soft quota limits are discussed in:


Section 6.7.3.1, Hard and Soft Quota Limits for the UFS File System

Section 7.5, Managing File System and Fileset Quotas for the AdvFS
File System

Section 9.3.4, Setting File System Quotas for the UFS File System

None of these sections discuss the fact that a hard limit is one more
unit (blocks, files, inodes) than will be allowed when the quota limit
is active.  The quota is up to, but not including the limit.  For
example, if you set a hard limit of 10,000 disk blocks for each user
account in a file system, an account reaches the hard limit when
9,999 disk blocks have been allocated.  If you want a maximum of
10,000 complete blocks for the user account, you must set the
hard limit to 10,001.











7.3.2    Environmental Monitoring



In the Environmental Monitoring section, the
System Administration
guide incorrectly states:

When a fan failure is encountered, a message is broadcasted and an
orderly shutdown ensues.

It should state:

When the cooling fan on an AlphaServer 1000A fails, the kernel
logs the error, synchronizes the disks, then powers the system
down.  On all other fan failures, a hard shutdown ensues.











7.3.3    User Definable Messages in Environmental Monitoring


You can modify any messages broadcast or logged by the Environmental
Monitoring utility.  The messages are located in the following file:

/usr/share/sysman/envmon/EnvMon_UserDefinable_Msg.tcl

You must be root to edit this file.  You can edit any message
included in braces ({}).  The instructions for editing this file
are included in the comment (#) fields.  Do not alter any other
data in this file.











7.4    Assembly Language Programmer's Guide



The
Assembly Language Programmer's Guide
(Chapter 5) should include a description of the
.rconst
directive.
This directive instructs the assembler to add subsequent data into the
.rconst
section.
This behavior is similar to the
.rdata
directive, except that the entries cannot be relocatable.











7.5    Programming with ONC RPC



Sections 2.1.5 and 2.1.6 of the
Programming with ONC RPC
guide are correct only for a DIGITAL UNIX system.  The code
may not be portable to other UNIX systems.

If the client machine is not another DIGITAL UNIX system, copy the
source code to the client.  Check that the header calls are
appropriate for the programming conventions on the client operating
system and then compile the code locally.











7.6    Developing Applications for the Display PostScript System



The guide for
Developing Applications for the Display PostScript System
refers to a nonexistent example directory
/usr/examples/dps.
None of the examples specified in the documentation are provided.











7.7    Gate Daemon Configuration Guide



References to the
Gate Daemon Configuration Guide
in the
Technical Overview
and possibly other books are obsolete because this document has been
removed from the
DIGITAL UNIX V4.0D Documentation, Volume 1
CD-ROM.  Information from the
Gate Daemon Configuration Guide
has been incorporated into the following
reference pages:
gated.conf(4),
gated.control(4),
gated.proto(4),
gated_intro(7),
and
gated(8).











7.8    Online Help Volumes


The notes in this section refer to problems with the online
help volumes.



For each of the SysMan applications,
online help is available from the Help menu or from
the Help button in the main window.

The online help contains:


An overview of the capabilities of the application

A set of tasks illustrating typical uses of the application

A reference section that documents every window and
dialog box in the application.

The Using Help item on the Help menu displays a help volume
that explains how to use the online help.

The Help viewer has the following known problems:


In some cases, the help viewer is not correctly initialized.
As a result, it will sometimes exhibit the expected behavior
the second time an action is taken, but not the first time.

For example, the first time a quick help dialog box
displays a reference page, the Backtrack button may be
enabled even though there is no place to which to backtrack.
If the dialog box is closed and then opened again,
the Backtrack button is dimmed.

Similarly, if a request for on-item help displays the
correct help, but one line has scrolled off the top,
the online help will typically be displayed
in exactly the right position when the on-item help
request is repeated.












7.8.1    General Problems


The following known problems occur in the online help:


The Appearance menu is not consistently documented.

In the Archiver, License Manager, and System Information applications,
there is an Appearance item
on one of the menus.  The item should offer three options:
Text Only, Large Icon, and Small Icon.  In some help volumes,
not all of these are documented.

Some links from one help volume to another are displayed in a new view.

There are a few links from one help volume to another
that appear in a new help viewer window.
In some situations, a distracting proliferation of help viewer windows
can result.

You can get a new view when you want one using the New Window
item on the File menu in the help viewer.












7.8.2    Integration


The SysMan configuration applications
on-item help does not work on the items
in the menu bar.

In all the SysMan applications, the keyboard
method of getting on-item help does not work
on the Help menu.











7.8.3    Update Path in Installation Online Help Is Incorrect




The update installation path shown in the installation online help is
not correct.  The Preinstall Review List in the installation online
help should state:

Your system must be running DIGITAL UNIX operating system Version
4.0A, Version 4.0B, or Version 4.0C in order to update to
DIGITAL UNIX Version 4.0D.













7.8.4    Help Volumes by Application


The following problems apply only to help in specific applications:


Kernel Tuner

The Kernel Tuner application records its changes immediately,
so if a system failure occurs while the Kernel Tuner is
running, any boot-time changes will take effect the next
time the system boots. If the
/etc/sysconfigtab
file contains invalid values,
you can enter the following command at the boot prompt to boot
with default values:


boot -fl c




Display Window

The help volume for Display Window has opening instructions
that show how to access the application from the
CDE Application Manager.  These should show that the
Display Window icon appears in two groups.

Network Configuration

The names of the
gated,
joind,
routed,
and
rwhod
daemons
are misspelled in the online help volume.

In the Configuring Interfaces dialog box, the fields under
To Obtain IP Address are relevant for all interfaces.

Printer Configuration

In the Local Printer Settings dialog box
and the Remote Printer Settings dialog box,
the aliases in the Printer Aliases field
must be separated by vertical bars because
spaces are allowed in an alias.

Shutdown

The
/usr/sbin/shutdown
command now sends the Shutdown Message
each time a reminder is sent of the time remaining before
the system is shut down.

The
/etc/nologin
file is not created until immediately before the shutdown occurs.

System shutdown messages are sent to all users that are locally or
remotely logged in to the system being shut down.  Additionally, if the
"Broadcast to NFS Clients" option is selected, shutdown messages are
broadcast to all hosts that are NFS clients of the system being
shut down.

Disk Configuration

The following corrected definitions replace the
definitions in the glossary for Disk Configuration.


Skew

A deviation from a reference direction,
either by design or in response to lateral forces.

Track skew

On a disk, the sector skew per track.
The skew is the angle that sector 0 of the track changes from
an imaginary radius line, due to a nonuniform
number of sectors per track.


BIND Configuration

The following corrected definitions replace the
definitions in the glossary for BIND Configuration:


BIND client

A system that queries a BIND server for host name and address
information, interprets the responses, and
passes the information to requesting applications.

BIND server

An authoritative source for information about one or more zones.
It either maintains the master copy of the hosts database
for the zone or obtains the information required to serve
the hosts database from another server.

DCE

Distributed Computing Environment.
The capabilities of DCE are defined by the
Open Software Foundation (OSF).

DCE cell

A logical group of systems that share services offered
by DCE.

DCE server

The server in a DCE cell.

service type

In BIND Configuration, the available
service types are BIND client and BIND server.
The service type determines whether a
system is configured to be a BIND client
or a BIND server.

7 Documentation Notes

7.1 Documentation Overview

7.2 Network Administration Guide

7.2.1 Section 4.2.2.2 (Verifying PPP Support in the Kernel) Is Obsolete

7.2.2 Sections 4.2.3.1, 4.2.3.2, and 4.2.3.3 Are Obsolete

7.2.2.1 Establishing a PPP Dial-Out Connection

7.2.2.2 Establishing a PPP Dial-In Connection

7.3 System Administration Guide

7.3.1 Hard Limit for File System Quotas

7.3.2 Environmental Monitoring

7.3.3 User Definable Messages in Environmental Monitoring

7.4 Assembly Language Programmer's Guide

7.5 Programming with ONC RPC

7.6 Developing Applications for the Display PostScript System

7.7 Gate Daemon Configuration Guide

7.8 Online Help Volumes

7.8.1 General Problems

7.8.2 Integration

7.8.3 Update Path in Installation Online Help Is Incorrect

7.8.4 Help Volumes by Application