aboutsummaryrefslogtreecommitdiff
path: root/en_US.ISO8859-1/books/handbook
diff options
context:
space:
mode:
Diffstat (limited to 'en_US.ISO8859-1/books/handbook')
-rw-r--r--en_US.ISO8859-1/books/handbook/Makefile2
-rw-r--r--en_US.ISO8859-1/books/handbook/bibliography/chapter.xml2
-rw-r--r--en_US.ISO8859-1/books/handbook/book.xml2
-rw-r--r--en_US.ISO8859-1/books/handbook/chapters.ent4
-rw-r--r--en_US.ISO8859-1/books/handbook/colophon.xml2
-rw-r--r--en_US.ISO8859-1/books/handbook/introduction/chapter.xml4
-rw-r--r--en_US.ISO8859-1/books/handbook/mirrors/chapter.xml1
-rw-r--r--en_US.ISO8859-1/books/handbook/users/Makefile15
-rw-r--r--en_US.ISO8859-1/books/handbook/users/chapter.xml1043
-rw-r--r--en_US.ISO8859-1/books/handbook/vinum/Makefile15
-rw-r--r--en_US.ISO8859-1/books/handbook/vinum/chapter.xml1251
11 files changed, 2331 insertions, 10 deletions
diff --git a/en_US.ISO8859-1/books/handbook/Makefile b/en_US.ISO8859-1/books/handbook/Makefile
index f2e41fc06f..fa7ad27323 100644
--- a/en_US.ISO8859-1/books/handbook/Makefile
+++ b/en_US.ISO8859-1/books/handbook/Makefile
@@ -39,8 +39,6 @@ DOC?= book
FORMATS?= html-split
-HAS_INDEX= true
-
INSTALL_COMPRESSED?= gz
INSTALL_ONLY_COMPRESSED?=
diff --git a/en_US.ISO8859-1/books/handbook/bibliography/chapter.xml b/en_US.ISO8859-1/books/handbook/bibliography/chapter.xml
index 2b7bdece60..da614bdf17 100644
--- a/en_US.ISO8859-1/books/handbook/bibliography/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/bibliography/chapter.xml
@@ -532,7 +532,7 @@
<ulink
url="http://www.FreeBSD.org/cgi/cvsweb.cgi/src/share/misc/bsd-family-tree"></ulink>
or
- <ulink type="html"
+ <ulink
url="file://localhost/usr/share/misc/bsd-family-tree"><filename>/usr/share/misc/bsd-family-tree</filename></ulink>
on a FreeBSD machine.</para>
</listitem>
diff --git a/en_US.ISO8859-1/books/handbook/book.xml b/en_US.ISO8859-1/books/handbook/book.xml
index e23d7ec009..59144256ac 100644
--- a/en_US.ISO8859-1/books/handbook/book.xml
+++ b/en_US.ISO8859-1/books/handbook/book.xml
@@ -295,7 +295,7 @@
&chap.eresources;
&chap.pgpkeys;
</part>
- &freebsd-glossary;
+ &chap.freebsd-glossary;
&chap.index;
&chap.colophon;
</book>
diff --git a/en_US.ISO8859-1/books/handbook/chapters.ent b/en_US.ISO8859-1/books/handbook/chapters.ent
index d5cd395e7f..0bcc64c5d7 100644
--- a/en_US.ISO8859-1/books/handbook/chapters.ent
+++ b/en_US.ISO8859-1/books/handbook/chapters.ent
@@ -63,7 +63,7 @@
<!ENTITY chap.eresources.www.index.inc SYSTEM "eresources.xml.www.index.inc">
<!ENTITY chap.eresources.www.inc SYSTEM "eresources.xml.www.inc">
<!ENTITY chap.pgpkeys SYSTEM "pgpkeys/chapter.xml">
- <!ENTITY chap.freebsd-glossary "&freebsd-glossary;">
- <!ENTITY chap.index SYSTEM "index.xml">
+ <!ENTITY chap.freebsd-glossary SYSTEM "../../share/xml/glossary.ent">
+ <!ENTITY chap.index "<index xmlns='http://docbook.org/ns/docbook'/>">
<!ENTITY chap.colophon SYSTEM "colophon.xml">
diff --git a/en_US.ISO8859-1/books/handbook/colophon.xml b/en_US.ISO8859-1/books/handbook/colophon.xml
index 0d93d9bb66..c583ddfe90 100644
--- a/en_US.ISO8859-1/books/handbook/colophon.xml
+++ b/en_US.ISO8859-1/books/handbook/colophon.xml
@@ -12,7 +12,7 @@
from XML into many different presentation formats using
XSLT. The printed version of this
document would not be possible without Donald Knuth's
- <application>&tex;</application> typesetting language, Leslie
+ &tex; typesetting language, Leslie
Lamport's <application>LaTeX</application>, or Sebastian Rahtz's
<application>JadeTeX</application> macro package.</para>
</colophon>
diff --git a/en_US.ISO8859-1/books/handbook/introduction/chapter.xml b/en_US.ISO8859-1/books/handbook/introduction/chapter.xml
index afbe796fcf..9adbd535d2 100644
--- a/en_US.ISO8859-1/books/handbook/introduction/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/introduction/chapter.xml
@@ -1185,7 +1185,7 @@
<term>The FreeBSD Handbook</term>
<listitem>
- <para><ulink type="html"
+ <para><ulink
url="file://localhost/usr/local/share/doc/freebsd/handbook/index.html"><filename>/usr/local/share/doc/freebsd/handbook/index.html</filename></ulink></para>
</listitem>
</varlistentry>
@@ -1194,7 +1194,7 @@
<term>The FreeBSD FAQ</term>
<listitem>
- <para><ulink type="html"
+ <para><ulink
url="file://localhost/usr/local/share/doc/freebsd/faq/index.html"><filename>/usr/local/share/doc/freebsd/faq/index.html</filename></ulink></para>
</listitem>
</varlistentry>
diff --git a/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml b/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml
index ba2dde8e6b..f46b6db93e 100644
--- a/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml
+++ b/en_US.ISO8859-1/books/handbook/mirrors/chapter.xml
@@ -899,7 +899,6 @@ Certificate information:
by a configuration file called the
<filename>supfile</filename>. There are some sample
<filename>supfiles</filename> in the directory <ulink
- type="html"
url="file://localhost/usr/share/examples/cvsup/"><filename>/usr/share/examples/cvsup/</filename></ulink>.</para>
<para>The information in a <filename>supfile</filename> answers
diff --git a/en_US.ISO8859-1/books/handbook/users/Makefile b/en_US.ISO8859-1/books/handbook/users/Makefile
new file mode 100644
index 0000000000..b44bd80628
--- /dev/null
+++ b/en_US.ISO8859-1/books/handbook/users/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= users/chapter.xml
+
+VPATH= ..
+
+MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= ${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/en_US.ISO8859-1/books/handbook/users/chapter.xml b/en_US.ISO8859-1/books/handbook/users/chapter.xml
new file mode 100644
index 0000000000..39f145021d
--- /dev/null
+++ b/en_US.ISO8859-1/books/handbook/users/chapter.xml
@@ -0,0 +1,1043 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!--
+ The FreeBSD Documentation Project
+
+ $FreeBSD$
+-->
+
+<chapter id="users">
+ <chapterinfo>
+ <authorgroup>
+ <author>
+ <firstname>Neil</firstname>
+ <surname>Blakey-Milner</surname>
+ <contrib>Contributed by </contrib>
+ </author>
+ </authorgroup>
+ <!-- Feb 2000 -->
+ </chapterinfo>
+
+ <title>Users and Basic Account Management</title>
+
+ <sect1 id="users-synopsis">
+ <title>Synopsis</title>
+
+ <para>&os; allows multiple users to use the computer at the same
+ time. While only one user can sit in front of the screen and
+ use the keyboard at any one time, any number of users can log
+ in to the system through the network. To use the system, every
+ user must have a user account.</para>
+
+ <para>After reading this chapter, you will know:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The differences between the various user accounts on a
+ &os; system.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to add and remove user accounts.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to change account details, such as the user's full
+ name or preferred shell.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to set limits on a per-account basis to control the
+ resources, such as memory and CPU time, that accounts and
+ groups of accounts are allowed to access.</para>
+ </listitem>
+
+ <listitem>
+ <para>How to use groups to make account management
+ easier.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Before reading this chapter, you should:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Understand the <link linkend="basics">basics of &unix;
+ and &os;</link>.</para>
+ </listitem>
+ </itemizedlist>
+ </sect1>
+
+ <sect1 id="users-introduction">
+ <title>Introduction</title>
+
+ <para>Since all access to the &os; system is achieved via accounts
+ and all processes are run by users, user and account management
+ is important.</para>
+
+ <para>Every account on a &os; system has certain information
+ associated with it to identify the account.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term>User name</term>
+
+ <listitem>
+ <para>The user name is typed at the <prompt>login:</prompt>
+ prompt. User names must be unique on the system as no two
+ users can have the same user name. There are a number of
+ rules for creating valid user names, documented in
+ &man.passwd.5;. Typically user names consist of eight or
+ fewer all lower case characters in order to maintain
+ backwards compatibility with applications.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Password</term>
+
+ <listitem>
+ <para>Each account has an associated password. While the
+ password can be blank, this is highly discouraged and
+ every account should have a password.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>User ID (<acronym>UID</acronym>)</term>
+
+ <listitem>
+ <para>The User ID (<acronym>UID</acronym>) is a number,
+ traditionally from 0 to 65535<footnote
+ id="users-largeuidgid">
+ <para>It is possible to use
+ <acronym>UID</acronym>s/<acronym>GID</acronym>s as
+ large as 4294967295, but such IDs can cause serious
+ problems with software that makes assumptions about
+ the values of IDs.</para>
+ </footnote>, used to uniquely identify the user to the
+ system. Internally, &os; uses the
+ <acronym>UID</acronym> to identify users. Commands that
+ allow a user name to be specified will first convert it to
+ the <acronym>UID</acronym>. Though unlikely, it is
+ possible for several accounts with different user names to
+ share the same <acronym>UID</acronym>. As far as &os; is
+ concerned, these accounts are one user.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Group ID (<acronym>GID</acronym>)</term>
+
+ <listitem>
+ <para>The Group ID (<acronym>GID</acronym>) is a number,
+ traditionally from 0 to 65535<footnoteref
+ linkend="users-largeuidgid"/>, used to uniquely identify
+ the primary group that the user belongs to. Groups are a
+ mechanism for controlling access to resources based on a
+ user's <acronym>GID</acronym> rather than their
+ <acronym>UID</acronym>. This can significantly reduce the
+ size of some configuration files. A user may also be a
+ member of more than one group.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Login class</term>
+
+ <listitem>
+ <para>Login classes are an extension to the group mechanism
+ that provide additional flexibility when tailoring the
+ system to different users.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Password change time</term>
+
+ <listitem>
+ <para>By default &os; does not force users to change their
+ passwords periodically. Password expiration can be
+ enforced on a per-user basis, forcing some or all users to
+ change their passwords after a certain amount of time has
+ elapsed.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Account expiry time</term>
+
+ <listitem>
+ <para>By default &os; does not expire accounts. When
+ creating accounts that need a limited lifespan, such as
+ student accounts in a school, specify the account expiry
+ date. After the expiry time has elapsed, the account
+ cannot be used to log in to the system, although the
+ account's directories and files will remain.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>User's full name</term>
+
+ <listitem>
+ <para>The user name uniquely identifies the account to &os;,
+ but does not necessarily reflect the user's real name.
+ This information can be associated with the
+ account.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>Home directory</term>
+
+ <listitem>
+ <para>The home directory is the full path to a directory on
+ the system. This is the user's starting directory when
+ the user logs in. A common convention is to put all user
+ home directories under <filename
+ class="directory">/home/<replaceable>username</replaceable></filename>
+ or <filename
+ class="directory">/usr/home/<replaceable>username</replaceable></filename>.
+ Each user stores their personal files and subdirectories
+ in their own home directory.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term>User shell</term>
+
+ <listitem>
+ <para>The shell provides the default environment users use
+ to interact with the system. There are many different
+ kinds of shells, and experienced users will have their own
+ preferences, which can be reflected in their account
+ settings.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>There are three main types of accounts: the <link
+ linkend="users-superuser">superuser</link>, <link
+ linkend="users-system">system accounts</link>, and <link
+ linkend="users-user">user accounts</link>. The superuser
+ account, usually called <username>root</username>, is used to
+ manage the system with no limitations on privileges. System
+ accounts are used to run services. User accounts are
+ assigned to real people and are used to log in and use the
+ system.</para>
+
+ <sect2 id="users-superuser">
+ <title>The Superuser Account</title>
+
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary>superuser (root)</secondary>
+ </indexterm>
+ <para>The superuser account, usually called
+ <username>root</username>, is used to perform system
+ administration tasks and should not be used for day-to-day
+ tasks like sending and receiving mail, general exploration of
+ the system, or programming.</para>
+
+ <para>This is because the superuser, unlike normal user
+ accounts, can operate without limits, and misuse of the
+ superuser account may result in spectacular disasters. User
+ accounts are unable to destroy the system by mistake, so it is
+ generally best to use normal user accounts whenever possible,
+ unless extra privilege is required.</para>
+
+ <para>Always double and triple-check any commands issued as the
+ superuser, since an extra space or missing character can mean
+ irreparable data loss.</para>
+
+ <para>Always create a user account for the system administrator
+ and use this account to log in to the system for general
+ usage. This applies equally to multi-user or single-user
+ systems. Later sections will discuss how to create additional
+ accounts and how to change between the normal user and
+ superuser.</para>
+ </sect2>
+
+ <sect2 id="users-system">
+ <title>System Accounts</title>
+
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary>system</secondary>
+ </indexterm>
+ <para>System accounts are used to run services such as DNS,
+ mail, and web servers. The reason for this is security; if
+ all services ran as the superuser, they could act without
+ restriction.</para>
+
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary><username>daemon</username></secondary>
+ </indexterm>
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary><username>operator</username></secondary>
+ </indexterm>
+ <para>Examples of system accounts are
+ <username>daemon</username>, <username>operator</username>,
+ <username>bind</username>, <username>news</username>, and
+ <username>www</username>.</para>
+
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary><username>nobody</username></secondary>
+ </indexterm>
+ <para><username>nobody</username> is the generic unprivileged
+ system account. However, the more services that use
+ <username>nobody</username>, the more files and processes that
+ user will become associated with, and hence the more
+ privileged that user becomes.</para>
+ </sect2>
+
+ <sect2 id="users-user">
+ <title>User Accounts</title>
+
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary>user</secondary>
+ </indexterm>
+ <para>User accounts are the primary means of access for real
+ people to the system. User accounts insulate the user and
+ the environment, preventing users from damaging the system
+ or other users, and allowing users to customize their
+ environment without affecting others.</para>
+
+ <para>Every person accessing the system should have a unique
+ user account. This allows the administrator to find out who
+ is doing what, prevents users from clobbering each others'
+ settings or reading each others' mail, and so forth.</para>
+
+ <para>Each user can set up their own environment to accommodate
+ their use of the system, by using alternate shells, editors,
+ key bindings, and language.</para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="users-modifying">
+ <title>Modifying Accounts</title>
+
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary>modifying</secondary>
+ </indexterm>
+
+ <para>&os; provides a variety of different commands to manage
+ user accounts. The most common commands are summarized below,
+ followed by more detailed examples of their usage.</para>
+
+ <informaltable frame="none" pgwide="1">
+ <tgroup cols="2">
+ <colspec colwidth="1*"/>
+ <colspec colwidth="2*"/>
+
+ <thead>
+ <row>
+ <entry>Command</entry>
+ <entry>Summary</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>&man.adduser.8;</entry>
+ <entry>The recommended command-line application for adding
+ new users.</entry>
+ </row>
+
+ <row>
+ <entry>&man.rmuser.8;</entry>
+ <entry>The recommended command-line application for
+ removing users.</entry>
+ </row>
+
+ <row>
+ <entry>&man.chpass.1;</entry>
+ <entry>A flexible tool for changing user database
+ information.</entry>
+ </row>
+
+ <row>
+ <entry>&man.passwd.1;</entry>
+ <entry>The simple command-line tool to change user
+ passwords.</entry>
+ </row>
+
+ <row>
+ <entry>&man.pw.8;</entry>
+ <entry>A powerful and flexible tool for modifying all
+ aspects of user accounts.</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+ <sect2 id="users-adduser">
+ <title><command>adduser</command></title>
+
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary>adding</secondary>
+ </indexterm>
+ <indexterm>
+ <primary><command>adduser</command></primary>
+ </indexterm>
+ <indexterm>
+ <primary><filename
+ class="directory">/usr/share/skel</filename></primary>
+ </indexterm>
+ <indexterm><primary>skeleton directory</primary></indexterm>
+ <para>&man.adduser.8; is a simple program for adding new users
+ When a new user is added, this program automatically updates
+ <filename>/etc/passwd</filename> and
+ <filename>/etc/group</filename>. It also creates a home
+ directory for the new user, copies in the default
+ configuration files from <filename
+ class="directory">/usr/share/skel</filename>, and can
+ optionally mail the new user a welcome message.</para>
+
+ <example>
+ <title>Adding a User on &os;</title>
+
+ <screen>&prompt.root; <userinput>adduser</userinput>
+Username: <userinput>jru</userinput>
+Full name: <userinput>J. Random User</userinput>
+Uid (Leave empty for default):
+Login group [jru]:
+Login group is jru. Invite jru into other groups? []: <userinput>wheel</userinput>
+Login class [default]:
+Shell (sh csh tcsh zsh nologin) [sh]: <userinput>zsh</userinput>
+Home directory [/home/jru]:
+Home directory permissions (Leave empty for default):
+Use password-based authentication? [yes]:
+Use an empty password? (yes/no) [no]:
+Use a random password? (yes/no) [no]:
+Enter password:
+Enter password again:
+Lock out the account after creation? [no]:
+Username : jru
+Password : ****
+Full Name : J. Random User
+Uid : 1001
+Class :
+Groups : jru wheel
+Home : /home/jru
+Shell : /usr/local/bin/zsh
+Locked : no
+OK? (yes/no): <userinput>yes</userinput>
+adduser: INFO: Successfully added (jru) to the user database.
+Add another user? (yes/no): <userinput>no</userinput>
+Goodbye!
+&prompt.root;</screen>
+ </example>
+
+ <note>
+ <para>Since the password is not echoed when typed, be careful
+ to not mistype the password when creating the user
+ account.</para>
+ </note>
+ </sect2>
+
+ <sect2 id="users-rmuser">
+ <title><command>rmuser</command></title>
+
+ <indexterm><primary><command>rmuser</command></primary></indexterm>
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary>removing</secondary>
+ </indexterm>
+
+ <para>To completely remove a user from the system use
+ &man.rmuser.8;. This command performs the following
+ steps:</para>
+
+ <procedure>
+ <step>
+ <para>Removes the user's &man.crontab.1; entry if one
+ exists.</para>
+ </step>
+
+ <step>
+ <para>Removes any &man.at.1; jobs belonging to the
+ user.</para>
+ </step>
+
+ <step>
+ <para>Kills all processes owned by the user.</para>
+ </step>
+
+ <step>
+ <para>Removes the user from the system's local password
+ file.</para>
+ </step>
+
+ <step>
+ <para>Removes the user's home directory, if it is owned by
+ the user.</para>
+ </step>
+
+ <step>
+ <para>Removes the incoming mail files belonging to the user
+ from <filename
+ class="directory">/var/mail</filename>.</para>
+ </step>
+
+ <step>
+ <para>Removes all files owned by the user from temporary
+ file storage areas such as <filename
+ class="directory">/tmp</filename>.</para>
+ </step>
+
+ <step>
+ <para>Finally, removes the username from all groups to which
+ it belongs in <filename>/etc/group</filename>.</para>
+
+ <note>
+ <para>If a group becomes empty and the group name is the
+ same as the username, the group is removed. This
+ complements the per-user unique groups created by
+ &man.adduser.8;.</para>
+ </note>
+ </step>
+ </procedure>
+
+ <para>&man.rmuser.8; cannot be used to remove superuser
+ accounts since that is almost always an indication of massive
+ destruction.</para>
+
+ <para>By default, an interactive mode is used, as shown
+ in the following example.</para>
+
+ <example>
+ <title><command>rmuser</command> Interactive Account
+ Removal</title>
+
+ <screen>&prompt.root; <userinput>rmuser jru</userinput>
+Matching password entry:
+jru:*:1001:1001::0:0:J. Random User:/home/jru:/usr/local/bin/zsh
+Is this the entry you wish to remove? <userinput>y</userinput>
+Remove user's home directory (/home/jru)? <userinput>y</userinput>
+Updating password file, updating databases, done.
+Updating group file: trusted (removing group jru -- personal group is empty) done.
+Removing user's incoming mail file /var/mail/jru: done.
+Removing files belonging to jru from /tmp: done.
+Removing files belonging to jru from /var/tmp: done.
+Removing files belonging to jru from /var/tmp/vi.recover: done.
+&prompt.root;</screen>
+ </example>
+ </sect2>
+
+ <sect2 id="users-chpass">
+ <title><command>chpass</command></title>
+
+ <indexterm><primary><command>chpass</command></primary></indexterm>
+ <para>&man.chpass.1; can be used to change user database
+ information such as passwords, shells, and personal
+ information.</para>
+
+ <para>Only the superuser can change other users' information and
+ passwords with &man.chpass.1;.</para>
+
+ <para>When passed no options, aside from an optional username,
+ &man.chpass.1; displays an editor containing user information.
+ When the user exists from the editor, the user database is
+ updated with the new information.</para>
+
+ <note>
+ <para>You will be asked for your password after exiting the
+ editor if you are not the superuser.</para>
+ </note>
+
+ <example>
+ <title>Interactive <command>chpass</command> by
+ Superuser</title>
+
+ <screen>#Changing user database information for jru.
+Login: jru
+Password: *
+Uid [#]: 1001
+Gid [# or name]: 1001
+Change [month day year]:
+Expire [month day year]:
+Class:
+Home directory: /home/jru
+Shell: /usr/local/bin/zsh
+Full Name: J. Random User
+Office Location:
+Office Phone:
+Home Phone:
+Other information:</screen>
+ </example>
+
+ <para>A user can change only a small subset of this
+ information, and only for their own user account.</para>
+
+ <example>
+ <title>Interactive <command>chpass</command> by Normal
+ User</title>
+
+ <screen>#Changing user database information for jru.
+Shell: /usr/local/bin/zsh
+Full Name: J. Random User
+Office Location:
+Office Phone:
+Home Phone:
+Other information:</screen>
+ </example>
+
+ <note>
+ <para>&man.chfn.1; and &man.chsh.1; are links to
+ &man.chpass.1;, as are &man.ypchpass.1;, &man.ypchfn.1;, and
+ &man.ypchsh.1;. <acronym>NIS</acronym> support is
+ automatic, so specifying the <literal>yp</literal> before
+ the command is not necessary. How to configure NIS is
+ covered in <xref linkend="network-servers"/>.</para>
+ </note>
+ </sect2>
+ <sect2 id="users-passwd">
+ <title><command>passwd</command></title>
+
+ <indexterm><primary><command>passwd</command></primary></indexterm>
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary>changing password</secondary>
+ </indexterm>
+ <para>&man.passwd.1; is the usual way to change your own
+ password as a user, or another user's password as the
+ superuser.</para>
+
+ <note>
+ <para>To prevent accidental or unauthorized changes, the user
+ must enter their original password before a new password can
+ be set. This is not the case when the superuser changes a
+ user's password.</para>
+ </note>
+
+ <example>
+ <title>Changing Your Password</title>
+
+ <screen>&prompt.user; <userinput>passwd</userinput>
+Changing local password for jru.
+Old password:
+New password:
+Retype new password:
+passwd: updating the database...
+passwd: done</screen>
+ </example>
+
+ <example>
+ <title>Changing Another User's Password as the
+ Superuser</title>
+
+ <screen>&prompt.root; <userinput>passwd jru</userinput>
+Changing local password for jru.
+New password:
+Retype new password:
+passwd: updating the database...
+passwd: done</screen>
+ </example>
+
+ <note>
+ <para>As with &man.chpass.1;, &man.yppasswd.1; is a link to
+ &man.passwd.1;, so NIS works with either command.</para>
+ </note>
+ </sect2>
+
+
+ <sect2 id="users-pw">
+ <title><command>pw</command></title>
+
+ <indexterm><primary><command>pw</command></primary></indexterm>
+
+ <para>&man.pw.8; is a command line utility to create, remove,
+ modify, and display users and groups. It functions as a front
+ end to the system user and group files. &man.pw.8; has a very
+ powerful set of command line options that make it suitable for
+ use in shell scripts, but new users may find it more
+ complicated than the other commands presented in this
+ section.</para>
+ </sect2>
+
+
+ </sect1>
+
+ <sect1 id="users-limiting">
+ <title>Limiting Users</title>
+
+ <indexterm><primary>limiting users</primary></indexterm>
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary>limiting</secondary>
+ </indexterm>
+ <para>&os; provides several methods for an administrator to limit
+ the amount of system resources an individual may use. These
+ limits are discussed in two sections: disk quotas and other
+ resource limits.</para>
+
+ <indexterm><primary>quotas</primary></indexterm>
+ <indexterm>
+ <primary>limiting users</primary>
+ <secondary>quotas</secondary>
+ </indexterm>
+ <indexterm><primary>disk quotas</primary></indexterm>
+ <para>Disk quotas limit the amount of disk space available to
+ users and provide a way to quickly check that usage without
+ calculating it every time. Quotas are discussed in <xref
+ linkend="quotas"/>.</para>
+
+ <para>The other resource limits include ways to limit the amount
+ of CPU, memory, and other resources a user may consume. These
+ are defined using login classes and are discussed here.</para>
+
+ <indexterm>
+ <primary><filename>/etc/login.conf</filename></primary>
+ </indexterm>
+ <para>Login classes are defined in
+ <filename>/etc/login.conf</filename> and are described in detail
+ in &man.login.conf.5;. Each user account is assigned to a login
+ class, <literal>default</literal> by default, and each login
+ class has a set of login capabilities associated with it. A
+ login capability is a
+ <literal><replaceable>name</replaceable>=<replaceable>value</replaceable></literal>
+ pair, where <replaceable>name</replaceable> is a well-known
+ identifier and <replaceable>value</replaceable> is an arbitrary
+ string which is processed accordingly depending on the
+ <replaceable>name</replaceable>. Setting up login classes and
+ capabilities is rather straightforward and is also described in
+ &man.login.conf.5;.</para>
+
+ <note>
+ <para>&os; does not normally read the configuration in
+ <filename>/etc/login.conf</filename> directly, but instead
+ reads the <filename>/etc/login.conf.db</filename> database
+ which provides faster lookups. Whenever
+ <filename>/etc/login.conf</filename> is edited, the
+ <filename>/etc/login.conf.db</filename> must be updated by
+ executing the following command:</para>
+
+ <screen>&prompt.root; <userinput>cap_mkdb /etc/login.conf</userinput></screen>
+ </note>
+
+ <para>Resource limits differ from the default login capabilities
+ in two ways. First, for every limit, there is a soft (current)
+ and hard limit. A soft limit may be adjusted by the user or
+ application, but may not be set higher than the hard limit. The
+ hard limit may be lowered by the user, but can only be raised
+ by the superuser. Second, most resource limits apply per
+ process to a specific user, not to the user as a whole. These
+ differences are mandated by the specific handling of the limits,
+ not by the implementation of the login capability
+ framework.</para>
+
+ <para>Below are the most commonly used resource limits. The rest
+ of the limits, along with all the other login capabilities, can
+ be found in &man.login.conf.5;.</para>
+
+ <variablelist>
+ <varlistentry>
+ <term><literal>coredumpsize</literal></term>
+
+ <listitem>
+ <para>The limit on the size of a core file<indexterm><primary>coredumpsize</primary></indexterm> generated by a
+ program is subordinate to other limits<indexterm><primary>limiting users</primary><secondary>coredumpsize</secondary></indexterm> on disk usage, such
+ as <literal>filesize</literal>, or disk quotas.
+ This limit is often used as a less-severe method of
+ controlling disk space consumption. Since users do not
+ generate core files themselves, and often do not delete
+ them, setting this may save them from running out of disk
+ space should a large program crash.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>cputime</literal></term>
+
+ <listitem>
+ <para>The maximum amount of CPU<indexterm><primary>cputime</primary></indexterm><indexterm><primary>limiting users</primary><secondary>cputime</secondary></indexterm> time a user's process may
+ consume. Offending processes will be killed by the
+ kernel.</para>
+
+ <note>
+ <para>This is a limit on CPU <emphasis>time</emphasis>
+ consumed, not percentage of the CPU as displayed in
+ some fields by &man.top.1; and &man.ps.1;.</para>
+ </note>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>filesize</literal></term>
+
+ <listitem>
+ <para>The maximum size of a file<indexterm><primary>filesize</primary></indexterm><indexterm><primary>limiting users</primary><secondary>filesize</secondary></indexterm> the user may own. Unlike
+ <link linkend="quotas">disk quotas</link>, this limit is
+ enforced on individual files, not the set of all files a
+ user owns.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>maxproc</literal></term>
+
+ <listitem>
+ <para>The maximum number of processes<indexterm><primary>maxproc</primary></indexterm><indexterm><primary>limiting users</primary><secondary>maxproc</secondary></indexterm> a user can run. This
+ includes foreground and background processes. This limit
+ may not be larger than the system limit specified by the
+ <varname>kern.maxproc</varname> &man.sysctl.8;. Setting
+ this limit too small may hinder a user's productivity as
+ it is often useful to be logged in multiple times or to
+ execute pipelines. Some tasks, such as compiling a large
+ program, spawn multiple processes and other intermediate
+ preprocessors.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>memorylocked</literal></term>
+
+ <listitem>
+ <para>The maximum amount of memory<indexterm><primary>memorylocked</primary></indexterm><indexterm><primary>limiting users</primary><secondary>memorylocked</secondary></indexterm> a process may request
+ to be locked into main memory using &man.mlock.2;. Some
+ system-critical programs, such as &man.amd.8;, lock into
+ main memory so that if the system begins to swap, they do
+ not contribute to disk thrashing.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>memoryuse</literal></term>
+
+ <listitem>
+ <para>The maximum amount of memory<indexterm><primary>memoryuse</primary></indexterm><indexterm><primary>limiting users</primary><secondary>memoryuse</secondary></indexterm> a process may consume at
+ any given time. It includes both core memory and swap
+ usage. This is not a catch-all limit for restricting
+ memory consumption, but is a good start.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>openfiles</literal></term>
+
+ <listitem>
+ <para>The maximum number of files a process may have open<indexterm><primary>openfiles</primary></indexterm><indexterm><primary>limiting users</primary><secondary>openfiles</secondary></indexterm>.
+ In &os;, files are used to represent sockets and IPC
+ channels, so be careful not to set this too low. The
+ system-wide limit for this is defined by the
+ <varname>kern.maxfiles</varname> &man.sysctl.8;.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>sbsize</literal></term>
+
+ <listitem>
+ <para>The limit on the amount of network memory, and
+ thus mbufs<indexterm><primary>sbsize</primary></indexterm><indexterm><primary>limiting users</primary><secondary>sbsize</secondary></indexterm>, a user may consume in order to limit network
+ communications.</para>
+ </listitem>
+ </varlistentry>
+
+ <varlistentry>
+ <term><literal>stacksize</literal></term>
+
+ <listitem>
+ <para>The maximum size of a process stack<indexterm><primary>stacksize</primary></indexterm><indexterm><primary>limiting users</primary><secondary>stacksize</secondary></indexterm>. This alone is
+ not sufficient to limit the amount of memory a program
+ may use so it should be used in conjunction with other
+ limits.</para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+
+ <para>There are a few other things to remember when setting
+ resource limits. Following are some general tips, suggestions,
+ and miscellaneous comments.</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Processes started at system startup by
+ <filename>/etc/rc</filename> are assigned to the
+ <literal>daemon</literal> login class.</para>
+ </listitem>
+
+ <listitem>
+ <para>Although the <filename>/etc/login.conf</filename> that
+ comes with the system is a good source of reasonable values
+ for most limits, they may not be appropriate for every
+ system. Setting a limit too high may open the system up to
+ abuse, while setting it too low may put a strain on
+ productivity.</para>
+ </listitem>
+
+ <listitem>
+ <para>Users of <application>&xorg;</application> should
+ probably be granted more resources than other users.
+ <application>&xorg;</application> by itself takes a lot of
+ resources, but it also encourages users to run more programs
+ simultaneously.</para>
+ </listitem>
+
+ <listitem>
+ <para>Many limits apply to individual processes, not the user
+ as a whole. For example, setting
+ <varname>openfiles</varname> to 50 means that each process
+ the user runs may open up to 50 files. The total amount
+ of files a user may open is the value of
+ <literal>openfiles</literal> multiplied by the value of
+ <literal>maxproc</literal>. This also applies to memory
+ consumption.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>For further information on resource limits and login classes
+ and capabilities in general, refer to &man.cap.mkdb.1;,
+ &man.getrlimit.2;, and &man.login.conf.5;.</para>
+ </sect1>
+
+ <sect1 id="users-groups">
+ <title>Groups</title>
+
+ <indexterm><primary>groups</primary></indexterm>
+ <indexterm>
+ <primary><filename>/etc/groups</filename></primary>
+ </indexterm>
+ <indexterm>
+ <primary>accounts</primary>
+ <secondary>groups</secondary>
+ </indexterm>
+ <para>A group is a list of users. A group is identified by its
+ group name and <acronym>GID</acronym>. In &os;, the
+ kernel uses the <acronym>UID</acronym> of a process, and the
+ list of groups it belongs to, to determine what the process is
+ allowed to do. Most of the time, the <acronym>GID</acronym> of
+ a user or process usually means the first group in the
+ list.</para>
+
+ <para>The group name to <acronym>GID</acronym> mapping is listed
+ in <filename>/etc/group</filename>. This is a plain text file
+ with four colon-delimited fields. The first field is the group
+ name, the second is the encrypted password, the third the
+ <acronym>GID</acronym>, and the fourth the comma-delimited list
+ of members. For a more complete description of the syntax,
+ refer to &man.group.5;.</para>
+
+ <para>The superuser can modify <filename>/etc/group</filename>
+ using a text editor. Alternatively, &man.pw.8; can be used to
+ add and edit groups. For example, to add a group called
+ <groupname>teamtwo</groupname> and then confirm that it
+ exists:</para>
+
+ <example>
+ <title>Adding a Group Using &man.pw.8;</title>
+
+ <screen>&prompt.root; <userinput>pw groupadd teamtwo</userinput>
+&prompt.root; <userinput>pw groupshow teamtwo</userinput>
+teamtwo:*:1100:</screen>
+ </example>
+
+ <para>In this example, <literal>1100</literal> is the
+ <acronym>GID</acronym> of <groupname>teamtwo</groupname>. Right
+ now, <groupname>teamtwo</groupname> has no members. This
+ command will add <username>jru</username> as a member of
+ <groupname>teamtwo</groupname>.</para>
+
+ <example>
+ <title>Adding User Accounts to a New Group Using
+ &man.pw.8;</title>
+
+ <screen>&prompt.root; <userinput>pw groupmod teamtwo -M jru</userinput>
+&prompt.root; <userinput>pw groupshow teamtwo</userinput>
+teamtwo:*:1100:jru</screen>
+ </example>
+
+ <para>The argument to <option>-M</option> is a comma-delimited
+ list of users to be added to a new (empty) group or to replace
+ the members of an existing group. To the user, this group
+ membership is different from (and in addition to) the user's
+ primary group listed in the password file. This means that
+ the user will not show up as a member when using
+ <option>groupshow</option> with &man.pw.8;, but will show up
+ when the information is queried via &man.id.1; or a similar
+ tool. When &man.pw.8; is used to add a user to a group, it only
+ manipulates <filename>/etc/group</filename> and does not attempt
+ to read additional data from
+ <filename>/etc/passwd</filename>.</para>
+
+ <example>
+ <title>Adding a New Member to a Group Using &man.pw.8;</title>
+
+ <screen>&prompt.root; <userinput>pw groupmod teamtwo -m db</userinput>
+&prompt.root; <userinput>pw groupshow teamtwo</userinput>
+teamtwo:*:1100:jru,db</screen>
+ </example>
+
+ <para>In this example, the argument to <option>-m</option> is a
+ comma-delimited list of users who are to be added to the group.
+ Unlike the previous example, these users are appended to the
+ group list and do not replace the list of existing users in the
+ group.</para>
+
+ <example>
+ <title>Using &man.id.1; to Determine Group Membership</title>
+
+ <screen>&prompt.user; <userinput>id jru</userinput>
+uid=1001(jru) gid=1001(jru) groups=1001(jru), 1100(teamtwo)</screen>
+ </example>
+
+ <para>In this example, <username>jru</username> is a member of the
+ groups <groupname>jru</groupname> and
+ <groupname>teamtwo</groupname>.</para>
+
+ <para>For more information about this command and the format of
+ <filename>/etc/group</filename>, refer to &man.pw.8; and
+ &man.group.5;.</para>
+ </sect1>
+
+ <sect1 id="users-becomesuper">
+ <title>Becoming Superuser</title>
+
+ <para>There are several ways to do things as the superuser. The
+ worst way is to log in as <username>root</username> directly.
+ Usually very little activity requires <username>root</username>
+ so logging off and logging in as <username>root</username>,
+ performing tasks, then logging off and on again as a normal user
+ is a waste of time.</para>
+
+ <para>A better way is to use &man.su.1; without providing a login
+ but using <literal>-</literal> to inherit the root environment.
+ Not providing a login will imply super user. For this to work
+ the login that must be in the <groupname>wheel</groupname> group.
+ An example of a typical software installation would involve the
+ administrator unpacking the software as a normal user and then
+ elevating their privileges for the build and installation of
+ the software.</para>
+
+ <example>
+ <title>Install a Program As The Superuser</title>
+
+ <screen>&prompt.user; <userinput>configure</userinput>
+&prompt.user; <userinput>make</userinput>
+&prompt.user; <userinput>su -</userinput>
+Password:
+&prompt.root; <userinput>make install</userinput>
+&prompt.root; <userinput>exit</userinput>
+&prompt.user;</screen>
+ </example>
+
+ <para>Note in this example the transition to
+ <username>root</username> is less painful than logging off
+ and back on twice.</para>
+
+ <para>Using &man.su.1; works well for single systems or small
+ networks with just one system administrator. For more complex
+ environments (or even for these simple environments)
+ <command>sudo</command> should be used. It is provided as a port,
+ <filename role="package">security/sudo</filename>. It allows for
+ things like activity logging, granting users the ability to only
+ run certain commands as the superuser, and several other
+ options.</para>
+ </sect1>
+</chapter>
diff --git a/en_US.ISO8859-1/books/handbook/vinum/Makefile b/en_US.ISO8859-1/books/handbook/vinum/Makefile
new file mode 100644
index 0000000000..b970524581
--- /dev/null
+++ b/en_US.ISO8859-1/books/handbook/vinum/Makefile
@@ -0,0 +1,15 @@
+#
+# Build the Handbook with just the content from this chapter.
+#
+# $FreeBSD$
+#
+
+CHAPTERS= vinum/chapter.xml
+
+VPATH= ..
+
+MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX}
+
+DOC_PREFIX?= ${.CURDIR}/../../../..
+
+.include "../Makefile"
diff --git a/en_US.ISO8859-1/books/handbook/vinum/chapter.xml b/en_US.ISO8859-1/books/handbook/vinum/chapter.xml
new file mode 100644
index 0000000000..0b0dc34114
--- /dev/null
+++ b/en_US.ISO8859-1/books/handbook/vinum/chapter.xml
@@ -0,0 +1,1251 @@
+<?xml version="1.0" encoding="iso-8859-1"?>
+<!--
+ The Vinum Volume Manager
+ By Greg Lehey (grog at lemis dot com)
+
+ Added to the Handbook by Hiten Pandya <hmp@FreeBSD.org>
+ and Tom Rhodes <trhodes@FreeBSD.org>
+
+ For the FreeBSD Documentation Project
+ $FreeBSD$
+-->
+
+<chapter id="vinum-vinum">
+ <chapterinfo>
+ <authorgroup>
+ <author>
+ <firstname>Greg</firstname>
+ <surname>Lehey</surname>
+ <contrib>Originally written by </contrib>
+ </author>
+ </authorgroup>
+ </chapterinfo>
+
+ <title>The <devicename>vinum</devicename> Volume Manager</title>
+
+ <sect1 id="vinum-synopsis">
+ <title>Synopsis</title>
+
+ <para>No matter the type of disks, there are always potential
+ problems. The disks can be too small, too slow, or too
+ unreliable to meet the system's requirements. While disks are
+ getting bigger, so are data storage requirements. Often a file
+ system is needed that is bigger than a disk's capacity. Various
+ solutions to these problems have been proposed and
+ implemented.</para>
+
+ <para>One method is through the use of multiple, and sometimes
+ redundant, disks. In addition to supporting various cards and
+ controllers for hardware Redundant Array of Independent
+ Disks <acronym>RAID</acronym> systems, the base &os; system
+ includes the <devicename>vinum</devicename> volume manager, a
+ block device driver that implements virtual disk drives and
+ addresses these three problems. <devicename>vinum</devicename>
+ provides more flexibility, performance, and reliability than
+ traditional disk storage and implements
+ <acronym>RAID</acronym>-0, <acronym>RAID</acronym>-1, and
+ <acronym>RAID</acronym>-5 models, both individually and in
+ combination.</para>
+
+ <para>This chapter provides an overview of potential problems with
+ traditional disk storage, and an introduction to the
+ <devicename>vinum</devicename> volume manager.</para>
+
+ <note>
+ <para>Starting with &os;&nbsp;5, <devicename>vinum</devicename>
+ has been rewritten in order to fit into the <link
+ linkend="GEOM">GEOM architecture</link>, while retaining the
+ original ideas, terminology, and on-disk metadata. This
+ rewrite is called <emphasis>gvinum</emphasis> (for <emphasis>
+ GEOM vinum</emphasis>). While this chapter uses the term
+ <devicename>vinum</devicename>, any command invocations should
+ be performed with <command>gvinum</command>. The name of the
+ kernel module has changed from the original
+ <filename>vinum.ko</filename> to
+ <filename>geom_vinum.ko</filename>, and all device nodes
+ reside under <filename
+ class="directory">/dev/gvinum</filename> instead of
+ <filename class="directory">/dev/vinum</filename>. As of
+ &os;&nbsp;6, the original <devicename>vinum</devicename>
+ implementation is no longer available in the code base.</para>
+ </note>
+ </sect1>
+
+ <sect1 id="vinum-access-bottlenecks">
+ <title>Access Bottlenecks</title>
+
+ <para>Modern systems frequently need to access data in a highly
+ concurrent manner. For example, large FTP or HTTP servers can
+ maintain thousands of concurrent sessions and have multiple
+ 100&nbsp;Mbit/s connections to the outside world, well beyond
+ the sustained transfer rate of most disks.</para>
+
+ <para>Current disk drives can transfer data sequentially at up to
+ 70&nbsp;MB/s, but this value is of little importance in an
+ environment where many independent processes access a drive, and
+ where they may achieve only a fraction of these values. In such
+ cases, it is more interesting to view the problem from the
+ viewpoint of the disk subsystem. The important parameter is the
+ load that a transfer places on the subsystem, or the time for
+ which a transfer occupies the drives involved in the
+ transfer.</para>
+
+ <para>In any disk transfer, the drive must first position the
+ heads, wait for the first sector to pass under the read head,
+ and then perform the transfer. These actions can be considered
+ to be atomic as it does not make any sense to interrupt
+ them.</para>
+
+ <para><anchor id="vinum-latency"/> Consider a typical transfer of
+ about 10&nbsp;kB: the current generation of high-performance
+ disks can position the heads in an average of 3.5&nbsp;ms. The
+ fastest drives spin at 15,000&nbsp;rpm, so the average
+ rotational latency (half a revolution) is 2&nbsp;ms. At
+ 70&nbsp;MB/s, the transfer itself takes about 150&nbsp;&mu;s,
+ almost nothing compared to the positioning time. In such a
+ case, the effective transfer rate drops to a little over
+ 1&nbsp;MB/s and is clearly highly dependent on the transfer
+ size.</para>
+
+ <para>The traditional and obvious solution to this bottleneck is
+ <quote>more spindles</quote>: rather than using one large disk,
+ use several smaller disks with the same aggregate storage
+ space. Each disk is capable of positioning and transferring
+ independently, so the effective throughput increases by a factor
+ close to the number of disks used.</para>
+
+ <para>The actual throughput improvement is smaller than the
+ number of disks involved. Although each drive is capable of
+ transferring in parallel, there is no way to ensure that the
+ requests are evenly distributed across the drives. Inevitably
+ the load on one drive will be higher than on another.</para>
+
+ <indexterm>
+ <primary>disk concatenation</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Vinum</primary>
+ <secondary>concatenation</secondary>
+ </indexterm>
+
+ <para>The evenness of the load on the disks is strongly dependent
+ on the way the data is shared across the drives. In the
+ following discussion, it is convenient to think of the disk
+ storage as a large number of data sectors which are addressable
+ by number, rather like the pages in a book. The most obvious
+ method is to divide the virtual disk into groups of consecutive
+ sectors the size of the individual physical disks and store them
+ in this manner, rather like taking a large book and tearing it
+ into smaller sections. This method is called
+ <emphasis>concatenation</emphasis> and has the advantage that
+ the disks are not required to have any specific size
+ relationships. It works well when the access to the virtual
+ disk is spread evenly about its address space. When access is
+ concentrated on a smaller area, the improvement is less marked.
+ <xref linkend="vinum-concat"/> illustrates the sequence in
+ which storage units are allocated in a concatenated
+ organization.</para>
+
+ <para>
+ <figure id="vinum-concat">
+ <title>Concatenated Organization</title>
+
+ <graphic fileref="vinum/vinum-concat"/>
+ </figure></para>
+
+ <indexterm>
+ <primary>disk striping</primary>
+ </indexterm>
+ <indexterm>
+ <primary>Vinum</primary>
+ <secondary>striping</secondary>
+ </indexterm>
+ <indexterm>
+ <primary><acronym>RAID</acronym></primary>
+ </indexterm>
+
+ <para>An alternative mapping is to divide the address space into
+ smaller, equal-sized components and store them sequentially on
+ different devices. For example, the first 256 sectors may be
+ stored on the first disk, the next 256 sectors on the next disk
+ and so on. After filling the last disk, the process repeats
+ until the disks are full. This mapping is called
+ <emphasis>striping</emphasis> or
+ <acronym>RAID-0</acronym>.</para>
+
+ <para><acronym>RAID</acronym> offers various forms of fault
+ tolerance, though <acronym>RAID-0</acronym> is somewhat
+ misleading as it provides no redundancy. Striping requires
+ somewhat more effort to locate the data, and it can cause
+ additional I/O load where a transfer is spread over multiple
+ disks, but it can also provide a more constant load across the
+ disks. <xref linkend="vinum-striped"/> illustrates the
+ sequence in which storage units are allocated in a striped
+ organization.</para>
+
+ <para>
+ <figure id="vinum-striped">
+ <title>Striped Organization</title>
+
+ <graphic fileref="vinum/vinum-striped"/>
+ </figure></para>
+ </sect1>
+
+ <sect1 id="vinum-data-integrity">
+ <title>Data Integrity</title>
+
+ <para>The final problem with disks is that they are unreliable.
+ Although reliability has increased tremendously over the last
+ few years, disk drives are still the most likely core component
+ of a server to fail. When they do, the results can be
+ catastrophic and replacing a failed disk drive and restoring
+ data can result in server downtime.</para>
+
+ <indexterm>
+ <primary>disk mirroring</primary>
+ </indexterm>
+ <indexterm><primary>vinum</primary>
+ <secondary>mirroring</secondary>
+ </indexterm>
+ <indexterm><primary><acronym>RAID</acronym>-1</primary>
+ </indexterm>
+
+ <para>One approach to this problem is
+ <emphasis>mirroring</emphasis>, or
+ <acronym>RAID-1</acronym>, which keeps two copies of the
+ data on different physical hardware. Any write to the volume
+ writes to both disks; a read can be satisfied from either, so if
+ one drive fails, the data is still available on the other
+ drive.</para>
+
+ <para>Mirroring has two problems:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>It requires twice as much disk storage as a
+ non-redundant solution.</para>
+ </listitem>
+
+ <listitem>
+ <para>Writes must be performed to both drives, so they take up
+ twice the bandwidth of a non-mirrored volume. Reads do not
+ suffer from a performance penalty and can even be
+ faster.</para>
+ </listitem>
+ </itemizedlist>
+
+ <indexterm><primary><acronym>RAID</acronym>-5</primary></indexterm>
+
+ <para>An alternative solution is <emphasis>parity</emphasis>,
+ implemented in <acronym>RAID</acronym> levels 2, 3, 4 and 5.
+ Of these, <acronym>RAID-5</acronym> is the most interesting. As
+ implemented in <devicename>vinum</devicename>, it is a variant
+ on a striped organization which dedicates one block of each
+ stripe to parity one of the other blocks. As implemented by
+ <devicename>vinum</devicename>, a
+ <acronym>RAID-5</acronym> plex is similar to a striped plex,
+ except that it implements <acronym>RAID-5</acronym> by
+ including a parity block in each stripe. As required by
+ <acronym>RAID-5</acronym>, the location of this parity block
+ changes from one stripe to the next. The numbers in the data
+ blocks indicate the relative block numbers.</para>
+
+ <para>
+ <figure id="vinum-raid5-org">
+ <title><acronym>RAID</acronym>-5 Organization</title>
+
+ <graphic fileref="vinum/vinum-raid5-org"/>
+ </figure></para>
+
+ <para>Compared to mirroring, <acronym>RAID-5</acronym> has the
+ advantage of requiring significantly less storage space. Read
+ access is similar to that of striped organizations, but write
+ access is significantly slower, approximately 25% of the read
+ performance. If one drive fails, the array can continue to
+ operate in degraded mode where a read from one of the remaining
+ accessible drives continues normally, but a read from the
+ failed drive is recalculated from the corresponding block from
+ all the remaining drives.</para>
+ </sect1>
+
+ <sect1 id="vinum-objects">
+ <title><devicename>vinum</devicename> Objects</title>
+
+ <para>In order to address these problems,
+ <devicename>vinum</devicename> implements a four-level hierarchy
+ of objects:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The most visible object is the virtual disk, called a
+ <emphasis>volume</emphasis>. Volumes have essentially the
+ same properties as a &unix; disk drive, though there are
+ some minor differences. For one, they have no size
+ limitations.</para>
+ </listitem>
+
+ <listitem>
+ <para>Volumes are composed of <emphasis>plexes</emphasis>,
+ each of which represent the total address space of a
+ volume. This level in the hierarchy provides redundancy.
+ Think of plexes as individual disks in a mirrored array,
+ each containing the same data.</para>
+ </listitem>
+
+ <listitem>
+ <para>Since <devicename>vinum</devicename> exists within the
+ &unix; disk storage framework, it would be possible to use
+ &unix; partitions as the building block for multi-disk
+ plexes. In fact, this turns out to be too inflexible as
+ &unix; disks can have only a limited number of partitions.
+ Instead, <devicename>vinum</devicename> subdivides a single
+ &unix; partition, the <emphasis>drive</emphasis>, into
+ contiguous areas called <emphasis>subdisks</emphasis>, which
+ are used as building blocks for plexes.</para>
+ </listitem>
+
+ <listitem>
+ <para>Subdisks reside on <devicename>vinum</devicename>
+ <emphasis>drives</emphasis>, currently &unix; partitions.
+ <devicename>vinum</devicename> drives can contain any
+ number of subdisks. With the exception of a small area at
+ the beginning of the drive, which is used for storing
+ configuration and state information, the entire drive is
+ available for data storage.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>The following sections describe the way these objects
+ provide the functionality required of
+ <devicename>vinum</devicename>.</para>
+
+ <sect2>
+ <title>Volume Size Considerations</title>
+
+ <para>Plexes can include multiple subdisks spread over all
+ drives in the <devicename>vinum</devicename> configuration.
+ As a result, the size of an individual drive does not limit
+ the size of a plex or a volume.</para>
+ </sect2>
+
+ <sect2>
+ <title>Redundant Data Storage</title>
+
+ <para><devicename>vinum</devicename> implements mirroring by
+ attaching multiple plexes to a volume. Each plex is a
+ representation of the data in a volume. A volume may contain
+ between one and eight plexes.</para>
+
+ <para>Although a plex represents the complete data of a volume,
+ it is possible for parts of the representation to be
+ physically missing, either by design (by not defining a
+ subdisk for parts of the plex) or by accident (as a result of
+ the failure of a drive). As long as at least one plex can
+ provide the data for the complete address range of the volume,
+ the volume is fully functional.</para>
+ </sect2>
+
+ <sect2>
+ <title>Which Plex Organization?</title>
+
+ <para><devicename>vinum</devicename> implements both
+ concatenation and striping at the plex level:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>A <emphasis>concatenated plex</emphasis> uses the
+ address space of each subdisk in turn. Concatenated
+ plexes are the most flexible as they can contain any
+ number of subdisks, and the subdisks may be of different
+ length. The plex may be extended by adding additional
+ subdisks. They require less <acronym>CPU</acronym>
+ time than striped plexes, though the difference in
+ <acronym>CPU</acronym> overhead is not measurable. On
+ the other hand, they are most susceptible to hot spots,
+ where one disk is very active and others are idle.</para>
+ </listitem>
+
+ <listitem>
+ <para>A <emphasis>striped plex</emphasis> stripes the data
+ across each subdisk. The subdisks must all be the same
+ size and there must be at least two subdisks in order to
+ distinguish it from a concatenated plex. The greatest
+ advantage of striped plexes is that they reduce hot spots.
+ By choosing an optimum sized stripe, about 256&nbsp;kB,
+ the load can be evened out on the component drives.
+ Extending a plex by adding new subdisks is so complicated
+ that <devicename>vinum</devicename> does not implement
+ it.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para><xref linkend="vinum-comparison"/> summarizes the
+ advantages and disadvantages of each plex organization.</para>
+
+ <table id="vinum-comparison" frame="none">
+ <title><devicename>vinum</devicename> Plex
+ Organizations</title>
+
+ <tgroup cols="5">
+ <thead>
+ <row>
+ <entry>Plex type</entry>
+ <entry>Minimum subdisks</entry>
+ <entry>Can add subdisks</entry>
+ <entry>Must be equal size</entry>
+ <entry>Application</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+ <entry>concatenated</entry>
+ <entry>1</entry>
+ <entry>yes</entry>
+ <entry>no</entry>
+ <entry>Large data storage with maximum placement
+ flexibility and moderate performance</entry>
+ </row>
+
+ <row>
+ <entry>striped</entry>
+ <entry>2</entry>
+ <entry>no</entry>
+ <entry>yes</entry>
+ <entry>High performance in combination with highly
+ concurrent access</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </sect2>
+ </sect1>
+
+ <sect1 id="vinum-examples">
+ <title>Some Examples</title>
+
+ <para><devicename>vinum</devicename> maintains a
+ <emphasis>configuration database</emphasis> which describes the
+ objects known to an individual system. Initially, the user
+ creates the configuration database from one or more
+ configuration files using &man.gvinum.8;.
+ <devicename>vinum</devicename> stores a copy of its
+ configuration database on each disk
+ <emphasis>device</emphasis> under its control. This database is
+ updated on each state change, so that a restart accurately
+ restores the state of each
+ <devicename>vinum</devicename> object.</para>
+
+ <sect2>
+ <title>The Configuration File</title>
+
+ <para>The configuration file describes individual
+ <devicename>vinum</devicename> objects. The definition of a
+ simple volume might be:</para>
+
+ <programlisting> drive a device /dev/da3h
+ volume myvol
+ plex org concat
+ sd length 512m drive a</programlisting>
+
+ <para>This file describes four <devicename>vinum</devicename>
+ objects:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The <emphasis>drive</emphasis> line describes a disk
+ partition (<emphasis>drive</emphasis>) and its location
+ relative to the underlying hardware. It is given the
+ symbolic name <emphasis>a</emphasis>. This separation of
+ symbolic names from device names allows disks to be moved
+ from one location to another without confusion.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <emphasis>volume</emphasis> line describes a
+ volume. The only required attribute is the name, in this
+ case <emphasis>myvol</emphasis>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <emphasis>plex</emphasis> line defines a plex.
+ The only required parameter is the organization, in this
+ case <emphasis>concat</emphasis>. No name is necessary as
+ the system automatically generates a name from the volume
+ name by adding the suffix
+ <emphasis>.p</emphasis><emphasis>x</emphasis>, where
+ <emphasis>x</emphasis> is the number of the plex in the
+ volume. Thus this plex will be called
+ <emphasis>myvol.p0</emphasis>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The <emphasis>sd</emphasis> line describes a subdisk.
+ The minimum specifications are the name of a drive on
+ which to store it, and the length of the subdisk. No name
+ is necessary as the system automatically assigns names
+ derived from the plex name by adding the suffix
+ <emphasis>.s</emphasis><emphasis>x</emphasis>, where
+ <emphasis>x</emphasis> is the number of the subdisk in
+ the plex. Thus <devicename>vinum</devicename> gives this
+ subdisk the name <emphasis>myvol.p0.s0</emphasis>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>After processing this file, &man.gvinum.8; produces the
+ following output:</para>
+
+ <programlisting width="97">
+ &prompt.root; gvinum -&gt; <userinput>create config1</userinput>
+ Configuration summary
+ Drives: 1 (4 configured)
+ Volumes: 1 (4 configured)
+ Plexes: 1 (8 configured)
+ Subdisks: 1 (16 configured)
+
+ D a State: up Device /dev/da3h Avail: 2061/2573 MB (80%)
+
+ V myvol State: up Plexes: 1 Size: 512 MB
+
+ P myvol.p0 C State: up Subdisks: 1 Size: 512 MB
+
+ S myvol.p0.s0 State: up PO: 0 B Size: 512 MB</programlisting>
+
+ <para>This output shows the brief listing format of
+ &man.gvinum.8;. It is represented graphically in <xref
+ linkend="vinum-simple-vol"/>.</para>
+
+ <para>
+ <figure id="vinum-simple-vol">
+ <title>A Simple <devicename>vinum</devicename>
+ Volume</title>
+
+ <graphic fileref="vinum/vinum-simple-vol"/>
+ </figure></para>
+
+ <para>This figure, and the ones which follow, represent a
+ volume, which contains the plexes, which in turn contains the
+ subdisks. In this example, the volume contains one plex, and
+ the plex contains one subdisk.</para>
+
+ <para>This particular volume has no specific advantage over a
+ conventional disk partition. It contains a single plex, so it
+ is not redundant. The plex contains a single subdisk, so
+ there is no difference in storage allocation from a
+ conventional disk partition. The following sections
+ illustrate various more interesting configuration
+ methods.</para>
+ </sect2>
+
+ <sect2>
+ <title>Increased Resilience: Mirroring</title>
+
+ <para>The resilience of a volume can be increased by mirroring.
+ When laying out a mirrored volume, it is important to ensure
+ that the subdisks of each plex are on different drives, so
+ that a drive failure will not take down both plexes. The
+ following configuration mirrors a volume:</para>
+
+ <programlisting> drive b device /dev/da4h
+ volume mirror
+ plex org concat
+ sd length 512m drive a
+ plex org concat
+ sd length 512m drive b</programlisting>
+
+ <para>In this example, it was not necessary to specify a
+ definition of drive <emphasis>a</emphasis> again, since
+ <devicename>vinum</devicename> keeps track of all objects in
+ its configuration database. After processing this definition,
+ the configuration looks like:</para>
+
+ <programlisting width="97">
+ Drives: 2 (4 configured)
+ Volumes: 2 (4 configured)
+ Plexes: 3 (8 configured)
+ Subdisks: 3 (16 configured)
+
+ D a State: up Device /dev/da3h Avail: 1549/2573 MB (60%)
+ D b State: up Device /dev/da4h Avail: 2061/2573 MB (80%)
+
+ V myvol State: up Plexes: 1 Size: 512 MB
+ V mirror State: up Plexes: 2 Size: 512 MB
+
+ P myvol.p0 C State: up Subdisks: 1 Size: 512 MB
+ P mirror.p0 C State: up Subdisks: 1 Size: 512 MB
+ P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB
+
+ S myvol.p0.s0 State: up PO: 0 B Size: 512 MB
+ S mirror.p0.s0 State: up PO: 0 B Size: 512 MB
+ S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB</programlisting>
+
+ <para><xref linkend="vinum-mirrored-vol"/> shows the
+ structure graphically.</para>
+
+ <para>
+ <figure id="vinum-mirrored-vol">
+ <title>A Mirrored <devicename>vinum</devicename>
+ Volume</title>
+
+ <graphic fileref="vinum/vinum-mirrored-vol"/>
+ </figure></para>
+
+ <para>In this example, each plex contains the full 512&nbsp;MB
+ of address space. As in the previous example, each plex
+ contains only a single subdisk.</para>
+ </sect2>
+
+ <sect2>
+ <title>Optimizing Performance</title>
+
+ <para>The mirrored volume in the previous example is more
+ resistant to failure than an unmirrored volume, but its
+ performance is less as each write to the volume requires a
+ write to both drives, using up a greater proportion of the
+ total disk bandwidth. Performance considerations demand a
+ different approach: instead of mirroring, the data is striped
+ across as many disk drives as possible. The following
+ configuration shows a volume with a plex striped across four
+ disk drives:</para>
+
+ <programlisting> drive c device /dev/da5h
+ drive d device /dev/da6h
+ volume stripe
+ plex org striped 512k
+ sd length 128m drive a
+ sd length 128m drive b
+ sd length 128m drive c
+ sd length 128m drive d</programlisting>
+
+ <para>As before, it is not necessary to define the drives which
+ are already known to <devicename>vinum</devicename>. After
+ processing this definition, the configuration looks
+ like:</para>
+
+ <programlisting width="92">
+ Drives: 4 (4 configured)
+ Volumes: 3 (4 configured)
+ Plexes: 4 (8 configured)
+ Subdisks: 7 (16 configured)
+
+ D a State: up Device /dev/da3h Avail: 1421/2573 MB (55%)
+ D b State: up Device /dev/da4h Avail: 1933/2573 MB (75%)
+ D c State: up Device /dev/da5h Avail: 2445/2573 MB (95%)
+ D d State: up Device /dev/da6h Avail: 2445/2573 MB (95%)
+
+ V myvol State: up Plexes: 1 Size: 512 MB
+ V mirror State: up Plexes: 2 Size: 512 MB
+ V striped State: up Plexes: 1 Size: 512 MB
+
+ P myvol.p0 C State: up Subdisks: 1 Size: 512 MB
+ P mirror.p0 C State: up Subdisks: 1 Size: 512 MB
+ P mirror.p1 C State: initializing Subdisks: 1 Size: 512 MB
+ P striped.p1 State: up Subdisks: 1 Size: 512 MB
+
+ S myvol.p0.s0 State: up PO: 0 B Size: 512 MB
+ S mirror.p0.s0 State: up PO: 0 B Size: 512 MB
+ S mirror.p1.s0 State: empty PO: 0 B Size: 512 MB
+ S striped.p0.s0 State: up PO: 0 B Size: 128 MB
+ S striped.p0.s1 State: up PO: 512 kB Size: 128 MB
+ S striped.p0.s2 State: up PO: 1024 kB Size: 128 MB
+ S striped.p0.s3 State: up PO: 1536 kB Size: 128 MB</programlisting>
+
+ <para>
+ <figure id="vinum-striped-vol">
+ <title>A Striped <devicename>vinum</devicename>
+ Volume</title>
+
+ <graphic fileref="vinum/vinum-striped-vol"/>
+ </figure></para>
+
+ <para>This volume is represented in <xref
+ linkend="vinum-striped-vol"/>. The darkness of the
+ stripes indicates the position within the plex address space,
+ where the lightest stripes come first and the darkest
+ last.</para>
+ </sect2>
+
+ <sect2>
+ <title>Resilience and Performance</title>
+
+ <para><anchor id="vinum-resilience"/>With sufficient hardware,
+ it is possible to build volumes which show both increased
+ resilience and increased performance compared to standard
+ &unix; partitions. A typical configuration file might
+ be:</para>
+
+ <programlisting> volume raid10
+ plex org striped 512k
+ sd length 102480k drive a
+ sd length 102480k drive b
+ sd length 102480k drive c
+ sd length 102480k drive d
+ sd length 102480k drive e
+ plex org striped 512k
+ sd length 102480k drive c
+ sd length 102480k drive d
+ sd length 102480k drive e
+ sd length 102480k drive a
+ sd length 102480k drive b</programlisting>
+
+ <para>The subdisks of the second plex are offset by two drives
+ from those of the first plex. This helps to ensure that
+ writes do not go to the same subdisks even if a transfer goes
+ over two drives.</para>
+
+ <para><xref linkend="vinum-raid10-vol"/> represents the
+ structure of this volume.</para>
+
+ <para>
+ <figure id="vinum-raid10-vol">
+ <title>A Mirrored, Striped <devicename>vinum</devicename>
+ Volume</title>
+
+ <graphic fileref="vinum/vinum-raid10-vol"/>
+ </figure></para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="vinum-object-naming">
+ <title>Object Naming</title>
+
+ <para><devicename>vinum</devicename> assigns default names to
+ plexes and subdisks, although they may be overridden.
+ Overriding the default names is not recommended as it does not
+ bring a significant advantage and it can cause
+ confusion.</para>
+
+ <para>Names may contain any non-blank character, but it is
+ recommended to restrict them to letters, digits and the
+ underscore characters. The names of volumes, plexes, and
+ subdisks may be up to 64 characters long, and the names of
+ drives may be up to 32 characters long.</para>
+
+ <para><devicename>vinum</devicename> objects are assigned device
+ nodes in the hierarchy <filename
+ class="directory">/dev/gvinum</filename>. The configuration
+ shown above would cause <devicename>vinum</devicename> to create
+ the following device nodes:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>Device entries for each volume. These are the main
+ devices used by <devicename>vinum</devicename>. The
+ configuration above would include the devices
+ <filename class="devicefile">/dev/gvinum/myvol</filename>,
+ <filename class="devicefile">/dev/gvinum/mirror</filename>,
+ <filename class="devicefile">/dev/gvinum/striped</filename>,
+ <filename class="devicefile">/dev/gvinum/raid5</filename>
+ and <filename
+ class="devicefile">/dev/gvinum/raid10</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para>All volumes get direct entries under
+ <filename class="directory">/dev/gvinum/</filename>.</para>
+ </listitem>
+
+ <listitem>
+ <para>The directories
+ <filename class="directory">/dev/gvinum/plex</filename>, and
+ <filename class="directory">/dev/gvinum/sd</filename>, which
+ contain device nodes for each plex and for each subdisk,
+ respectively.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>For example, consider the following configuration
+ file:</para>
+
+ <programlisting> drive drive1 device /dev/sd1h
+ drive drive2 device /dev/sd2h
+ drive drive3 device /dev/sd3h
+ drive drive4 device /dev/sd4h
+ volume s64 setupstate
+ plex org striped 64k
+ sd length 100m drive drive1
+ sd length 100m drive drive2
+ sd length 100m drive drive3
+ sd length 100m drive drive4</programlisting>
+
+ <para>After processing this file, &man.gvinum.8; creates the
+ following structure in <filename
+ class="directory">/dev/gvinum</filename>:</para>
+
+ <programlisting> drwxr-xr-x 2 root wheel 512 Apr 13
+16:46 plex
+ crwxr-xr-- 1 root wheel 91, 2 Apr 13 16:46 s64
+ drwxr-xr-x 2 root wheel 512 Apr 13 16:46 sd
+
+ /dev/vinum/plex:
+ total 0
+ crwxr-xr-- 1 root wheel 25, 0x10000002 Apr 13 16:46 s64.p0
+
+ /dev/vinum/sd:
+ total 0
+ crwxr-xr-- 1 root wheel 91, 0x20000002 Apr 13 16:46 s64.p0.s0
+ crwxr-xr-- 1 root wheel 91, 0x20100002 Apr 13 16:46 s64.p0.s1
+ crwxr-xr-- 1 root wheel 91, 0x20200002 Apr 13 16:46 s64.p0.s2
+ crwxr-xr-- 1 root wheel 91, 0x20300002 Apr 13 16:46 s64.p0.s3</programlisting>
+
+ <para>Although it is recommended that plexes and subdisks should
+ not be allocated specific names,
+ <devicename>vinum</devicename> drives must be named. This makes
+ it possible to move a drive to a different location and still
+ recognize it automatically. Drive names may be up to 32
+ characters long.</para>
+
+ <sect2>
+ <title>Creating File Systems</title>
+
+ <para>Volumes appear to the system to be identical to disks,
+ with one exception. Unlike &unix; drives,
+ <devicename>vinum</devicename> does not partition volumes,
+ which thus do not contain a partition table. This has
+ required modification to some disk utilities, notably
+ &man.newfs.8;, so that it does not try to interpret the last
+ letter of a <devicename>vinum</devicename> volume name as a
+ partition identifier. For example, a disk drive may have a
+ name like <filename class="devicefile">/dev/ad0a</filename>
+ or <filename class="devicefile">/dev/da2h</filename>. These
+ names represent the first partition
+ (<devicename>a</devicename>) on the first (0) IDE disk
+ (<devicename>ad</devicename>) and the eighth partition
+ (<devicename>h</devicename>) on the third (2) SCSI disk
+ (<devicename>da</devicename>) respectively. By contrast, a
+ <devicename>vinum</devicename> volume might be called
+ <filename class="devicefile">/dev/gvinum/concat</filename>,
+ which has no relationship with a partition name.</para>
+
+ <para>In order to create a file system on this volume, use
+ &man.newfs.8;:</para>
+
+ <screen>&prompt.root; <userinput>newfs /dev/gvinum/concat</userinput></screen>
+ </sect2>
+ </sect1>
+
+ <sect1 id="vinum-config">
+ <title>Configuring <devicename>vinum</devicename></title>
+
+ <para>The <filename>GENERIC</filename> kernel does not contain
+ <devicename>vinum</devicename>. It is possible to build a
+ custom kernel which includes <devicename>vinum</devicename>, but
+ this is not recommended. The standard way to start
+ <devicename>vinum</devicename> is as a kernel module.
+ &man.kldload.8; is not needed because when &man.gvinum.8;
+ starts, it checks whether the module has been loaded, and if it
+ is not, it loads it automatically.</para>
+
+
+ <sect2>
+ <title>Startup</title>
+
+ <para><devicename>vinum</devicename> stores configuration
+ information on the disk slices in essentially the same form as
+ in the configuration files. When reading from the
+ configuration database, <devicename>vinum</devicename>
+ recognizes a number of keywords which are not allowed in the
+ configuration files. For example, a disk configuration might
+ contain the following text:</para>
+
+ <programlisting width="119">volume myvol state up
+volume bigraid state down
+plex name myvol.p0 state up org concat vol myvol
+plex name myvol.p1 state up org concat vol myvol
+plex name myvol.p2 state init org striped 512b vol myvol
+plex name bigraid.p0 state initializing org raid5 512b vol bigraid
+sd name myvol.p0.s0 drive a plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 0b
+sd name myvol.p0.s1 drive b plex myvol.p0 state up len 1048576b driveoffset 265b plexoffset 1048576b
+sd name myvol.p1.s0 drive c plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 0b
+sd name myvol.p1.s1 drive d plex myvol.p1 state up len 1048576b driveoffset 265b plexoffset 1048576b
+sd name myvol.p2.s0 drive a plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 0b
+sd name myvol.p2.s1 drive b plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 524288b
+sd name myvol.p2.s2 drive c plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1048576b
+sd name myvol.p2.s3 drive d plex myvol.p2 state init len 524288b driveoffset 1048841b plexoffset 1572864b
+sd name bigraid.p0.s0 drive a plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 0b
+sd name bigraid.p0.s1 drive b plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 4194304b
+sd name bigraid.p0.s2 drive c plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 8388608b
+sd name bigraid.p0.s3 drive d plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 12582912b
+sd name bigraid.p0.s4 drive e plex bigraid.p0 state initializing len 4194304b driveoff set 1573129b plexoffset 16777216b</programlisting>
+
+ <para>The obvious differences here are the presence of
+ explicit location information and naming, both of which are
+ allowed but discouraged, and the information on the states.
+ <devicename>vinum</devicename> does not store information
+ about drives in the configuration information. It finds the
+ drives by scanning the configured disk drives for partitions
+ with a <devicename>vinum</devicename> label. This enables
+ <devicename>vinum</devicename> to identify drives correctly
+ even if they have been assigned different &unix; drive
+ IDs.</para>
+
+ <sect3 id="vinum-rc-startup">
+ <title>Automatic Startup</title>
+
+ <para><emphasis>Gvinum</emphasis> always features an
+ automatic startup once the kernel module is loaded, via
+ &man.loader.conf.5;. To load the
+ <emphasis>Gvinum</emphasis> module at boot time, add
+ <literal>geom_vinum_load="YES"</literal> to
+ <filename>/boot/loader.conf</filename>.</para>
+
+ <para>When <devicename>vinum</devicename> is started with
+ <command>gvinum start</command>,
+ <devicename>vinum</devicename> reads the configuration
+ database from one of the <devicename>vinum</devicename>
+ drives. Under normal circumstances, each drive contains
+ an identical copy of the configuration database, so it
+ does not matter which drive is read. After a crash,
+ however, <devicename>vinum</devicename> must determine
+ which drive was updated most recently and read the
+ configuration from this drive. It then updates the
+ configuration, if necessary, from progressively older
+ drives.</para>
+ </sect3>
+ </sect2>
+ </sect1>
+
+ <sect1 id="vinum-root">
+ <title>Using <devicename>vinum</devicename> for the Root
+ File System</title>
+
+ <para>For a machine that has fully-mirrored file systems using
+ <devicename>vinum</devicename>, it is desirable to also
+ mirror the root file system. Setting up such a configuration
+ is less trivial than mirroring an arbitrary file system
+ because:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The root file system must be available very early
+ during the boot process, so the
+ <devicename>vinum</devicename> infrastructure must
+ already be available at this time.</para>
+ </listitem>
+ <listitem>
+ <para>The volume containing the root file system also
+ contains the system bootstrap and the kernel. These must
+ be read using the host system's native utilities, such as
+ the BIOS, which often cannot be taught about the details
+ of <devicename>vinum</devicename>.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>In the following sections, the term <quote>root
+ volume</quote> is generally used to describe the
+ <devicename>vinum</devicename> volume that contains the root
+ file system.</para>
+
+ <sect2>
+ <title>Starting up <devicename>vinum</devicename> Early
+ Enough for the Root File System</title>
+
+ <para><devicename>vinum</devicename> must be available early
+ in the system boot as &man.loader.8; must be able to load
+ the vinum kernel module before starting the kernel. This
+ can be accomplished by putting this line in
+ <filename>/boot/loader.conf</filename>:</para>
+
+ <programlisting>geom_vinum_load="YES"</programlisting>
+
+ </sect2>
+
+ <sect2>
+ <title>Making a <devicename>vinum</devicename>-based Root
+ Volume Accessible to the Bootstrap</title>
+
+ <para>The current &os; bootstrap is only 7.5 KB of code and
+ does not understand the internal
+ <devicename>vinum</devicename> structures. This means that it
+ cannot parse the <devicename>vinum</devicename> configuration
+ data or figure out the elements of a boot volume. Thus, some
+ workarounds are necessary to provide the bootstrap code with
+ the illusion of a standard <literal>a</literal> partition
+ that contains the root file system.</para>
+
+ <para>For this to be possible, the following requirements must
+ be met for the root volume:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>The root volume must not be a stripe or
+ <acronym>RAID</acronym>-5.</para>
+ </listitem>
+
+ <listitem>
+ <para>The root volume must not contain more than one
+ concatenated subdisk per plex.</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Note that it is desirable and possible to use multiple
+ plexes, each containing one replica of the root file system.
+ The bootstrap process will only use one replica for finding
+ the bootstrap and all boot files, until the kernel mounts the
+ root file system. Each single subdisk within these plexes
+ needs its own <literal>a</literal> partition illusion, for
+ the respective device to be bootable. It is not strictly
+ needed that each of these faked <literal>a</literal>
+ partitions is located at the same offset within its device,
+ compared with other devices containing plexes of the root
+ volume. However, it is probably a good idea to create the
+ <devicename>vinum</devicename> volumes that way so the
+ resulting mirrored devices are symmetric, to avoid
+ confusion.</para>
+
+ <para>In order to set up these <literal>a</literal>
+ partitions for each device containing part of the root
+ volume, the following is required:</para>
+
+ <procedure>
+ <step>
+ <para>The location, offset from the beginning of the device,
+ and size of this device's subdisk that is part of the root
+ volume needs to be examined, using the command:</para>
+
+ <screen>&prompt.root; <userinput>gvinum l -rv root</userinput></screen>
+
+ <para><devicename>vinum</devicename> offsets and sizes are
+ measured in bytes. They must be divided by 512 in order
+ to obtain the block numbers that are to be used by
+ <command>bsdlabel</command>.</para>
+ </step>
+
+ <step>
+ <para>Run this command for each device that participates in
+ the root volume:</para>
+
+ <screen>&prompt.root; <userinput>bsdlabel -e <replaceable>devname</replaceable></userinput></screen>
+
+ <para><replaceable>devname</replaceable> must be either the
+ name of the disk, like <devicename>da0</devicename> for
+ disks without a slice table, or the name of the
+ slice, like <devicename>ad0s1</devicename>.</para>
+
+ <para>If there is already an <literal>a</literal>
+ partition on the device from a
+ pre-<devicename>vinum</devicename> root file system, it
+ should be renamed to something else so that it remains
+ accessible (just in case), but will no longer be used by
+ default to bootstrap the system. A currently mounted root
+ file system cannot be renamed, so this must be executed
+ either when being booted from a <quote>Fixit</quote>
+ media, or in a two-step process where, in a mirror, the
+ disk that is not been currently booted is manipulated
+ first.</para>
+
+ <para>The offset of the <devicename>vinum</devicename>
+ partition on this device (if any) must be added to the
+ offset of the respective root volume subdisk on this
+ device. The resulting value will become the
+ <literal>offset</literal> value for the new
+ <literal>a</literal> partition. The
+ <literal>size</literal> value for this partition can be
+ taken verbatim from the calculation above. The
+ <literal>fstype</literal> should be
+ <literal>4.2BSD</literal>. The
+ <literal>fsize</literal>, <literal>bsize</literal>,
+ and <literal>cpg</literal> values should be chosen
+ to match the actual file system, though they are fairly
+ unimportant within this context.</para>
+
+ <para>That way, a new <literal>a</literal> partition will
+ be established that overlaps the
+ <devicename>vinum</devicename> partition on this device.
+ <command>bsdlabel</command> will only allow for this
+ overlap if the <devicename>vinum</devicename> partition
+ has properly been marked using the
+ <literal>vinum</literal> fstype.</para>
+ </step>
+
+ <step>
+ <para>A faked <literal>a</literal> partition now exists
+ on each device that has one replica of the root volume.
+ It is highly recommendable to verify the result using a
+ command like:</para>
+
+ <screen>&prompt.root; <userinput>fsck -n /dev/<replaceable>devname</replaceable>a</userinput></screen>
+ </step>
+ </procedure>
+
+ <para>It should be remembered that all files containing control
+ information must be relative to the root file system in the
+ <devicename>vinum</devicename> volume which, when setting up
+ a new <devicename>vinum</devicename> root volume, might not
+ match the root file system that is currently active. So in
+ particular, <filename>/etc/fstab</filename> and
+ <filename>/boot/loader.conf</filename> need to be taken care
+ of.</para>
+
+ <para>At next reboot, the bootstrap should figure out the
+ appropriate control information from the new
+ <devicename>vinum</devicename>-based root file system, and act
+ accordingly. At the end of the kernel initialization process,
+ after all devices have been announced, the prominent notice
+ that shows the success of this setup is a message like:</para>
+
+ <screen>Mounting root from ufs:/dev/gvinum/root</screen>
+ </sect2>
+
+ <sect2>
+ <title>Example of a <devicename>vinum</devicename>-based Root
+ Setup</title>
+
+ <para>After the <devicename>vinum</devicename> root volume has
+ been set up, the output of <command>gvinum l -rv
+ root</command> could look like:</para>
+
+ <screen>...
+Subdisk root.p0.s0:
+ Size: 125829120 bytes (120 MB)
+ State: up
+ Plex root.p0 at offset 0 (0 B)
+ Drive disk0 (/dev/da0h) at offset 135680 (132 kB)
+
+Subdisk root.p1.s0:
+ Size: 125829120 bytes (120 MB)
+ State: up
+ Plex root.p1 at offset 0 (0 B)
+ Drive disk1 (/dev/da1h) at offset 135680 (132 kB)</screen>
+
+ <para>The values to note are <literal>135680</literal> for the
+ offset, relative to partition
+ <filename class="devicefile">/dev/da0h</filename>. This
+ translates to 265 512-byte disk blocks in
+ <command>bsdlabel</command>'s terms. Likewise, the size of
+ this root volume is 245760 512-byte blocks. <filename
+ class="devicefile">/dev/da1h</filename>, containing the
+ second replica of this root volume, has a symmetric
+ setup.</para>
+
+ <para>The bsdlabel for these devices might look like:</para>
+
+ <screen>...
+8 partitions:
+# size offset fstype [fsize bsize bps/cpg]
+ a: 245760 281 4.2BSD 2048 16384 0 # (Cyl. 0*- 15*)
+ c: 71771688 0 unused 0 0 # (Cyl. 0 - 4467*)
+ h: 71771672 16 vinum # (Cyl. 0*- 4467*)</screen>
+
+ <para>It can be observed that the <literal>size</literal>
+ parameter for the faked <literal>a</literal> partition
+ matches the value outlined above, while the
+ <literal>offset</literal> parameter is the sum of the offset
+ within the <devicename>vinum</devicename> partition
+ <literal>h</literal>, and the offset of this partition
+ within the device or slice. This is a typical setup that is
+ necessary to avoid the problem described in <xref
+ linkend="vinum-root-panic"/>. The entire
+ <literal>a</literal> partition is completely within the
+ <literal>h</literal> partition containing all the
+ <devicename>vinum</devicename> data for this device.</para>
+
+ <para>In the above example, the entire device is dedicated to
+ <devicename>vinum</devicename> and there is no leftover
+ pre-<devicename>vinum</devicename> root partition.</para>
+ </sect2>
+
+ <sect2>
+ <title>Troubleshooting</title>
+
+ <para>The following list contains a few known pitfalls and
+ solutions.</para>
+
+ <sect3>
+ <title>System Bootstrap Loads, but System Does Not
+ Boot</title>
+
+ <para>If for any reason the system does not continue to boot,
+ the bootstrap can be interrupted by pressing
+ <keycap>space</keycap> at the 10-seconds warning. The
+ loader variable <literal>vinum.autostart</literal> can be
+ examined by typing <command>show</command> and manipulated
+ using <command>set</command> or
+ <command>unset</command>.</para>
+
+ <para>If the <devicename>vinum</devicename> kernel module was
+ not yet in the list of modules to load automatically, type
+ <command>load geom_vinum</command>.</para>
+
+ <para>When ready, the boot process can be continued by typing
+ <command>boot -as</command> which
+ <option>-as</option> requests the kernel to ask for the
+ root file system to mount (<option>-a</option>) and make the
+ boot process stop in single-user mode (<option>-s</option>),
+ where the root file system is mounted read-only. That way,
+ even if only one plex of a multi-plex volume has been
+ mounted, no data inconsistency between plexes is being
+ risked.</para>
+
+ <para>At the prompt asking for a root file system to mount,
+ any device that contains a valid root file system can be
+ entered. If <filename>/etc/fstab</filename> is set up
+ correctly, the default should be something like
+ <literal>ufs:/dev/gvinum/root</literal>. A typical
+ alternate choice would be something like
+ <literal>ufs:da0d</literal> which could be a
+ hypothetical partition containing the
+ pre-<devicename>vinum</devicename> root file system. Care
+ should be taken if one of the alias
+ <literal>a</literal> partitions is entered here, that it
+ actually references the subdisks of the
+ <devicename>vinum</devicename> root device, because in a
+ mirrored setup, this would only mount one piece of a
+ mirrored root device. If this file system is to be mounted
+ read-write later on, it is necessary to remove the other
+ plex(es) of the <devicename>vinum</devicename> root volume
+ since these plexes would otherwise carry inconsistent
+ data.</para>
+ </sect3>
+
+ <sect3>
+ <title>Only Primary Bootstrap Loads</title>
+
+ <para>If <filename>/boot/loader</filename> fails to load, but
+ the primary bootstrap still loads (visible by a single dash
+ in the left column of the screen right after the boot
+ process starts), an attempt can be made to interrupt the
+ primary bootstrap by pressing
+ <keycap>space</keycap>. This will make the bootstrap stop
+ in <link linkend="boot-boot1">stage two</link>. An attempt
+ can be made here to boot off an alternate partition, like
+ the partition containing the previous root file system that
+ has been moved away from <literal>a</literal>.</para>
+ </sect3>
+
+ <sect3 id="vinum-root-panic">
+ <title>Nothing Boots, the Bootstrap
+ Panics</title>
+
+ <para>This situation will happen if the bootstrap had been
+ destroyed by the <devicename>vinum</devicename>
+ installation. Unfortunately, <devicename>vinum</devicename>
+ accidentally leaves only 4 KB at the beginning of its
+ partition free before starting to write its
+ <devicename>vinum</devicename> header information. However,
+ the stage one and two bootstraps plus the bsdlabel require 8
+ KB. So if a <devicename>vinum</devicename> partition was
+ started at offset 0 within a slice or disk that was meant to
+ be bootable, the <devicename>vinum</devicename> setup will
+ trash the bootstrap.</para>
+
+ <para>Similarly, if the above situation has been recovered,
+ by booting from a <quote>Fixit</quote> media, and the
+ bootstrap has been re-installed using
+ <command>bsdlabel -B</command> as described in <xref
+ linkend="boot-boot1"/>, the bootstrap will trash the
+ <devicename>vinum</devicename> header, and
+ <devicename>vinum</devicename> will no longer find its
+ disk(s). Though no actual <devicename>vinum</devicename>
+ configuration data or data in <devicename>vinum</devicename>
+ volumes will be trashed, and it would be possible to recover
+ all the data by entering exactly the same
+ <devicename>vinum</devicename> configuration data again, the
+ situation is hard to fix. It is necessary to move the
+ entire <devicename>vinum</devicename> partition by at least
+ 4 KB, in order to have the <devicename>vinum</devicename>
+ header and the system bootstrap no longer collide.</para>
+ </sect3>
+ </sect2>
+ </sect1>
+</chapter>