diff --git a/en_US.ISO8859-1/books/handbook/Makefile b/en_US.ISO8859-1/books/handbook/Makefile index b0dca1956f..c46632ff39 100644 --- a/en_US.ISO8859-1/books/handbook/Makefile +++ b/en_US.ISO8859-1/books/handbook/Makefile @@ -1,257 +1,259 @@ # # $FreeBSD$ # # Build the FreeBSD Handbook. # # ------------------------------------------------------------------------ # # Handbook-specific variables # # WITH_PGPKEYS The print version of the handbook only prints PGP # fingerprints by default. If you would like for the # entire key to be displayed, then set this variable. # This option has no affect on the HTML formats. # # Handbook-specific targets # # pgpkeyring This target will read the contents of # pgpkeys/chapter.sgml and will extract all of # the pgpkeys to standard out. This output can then # be redirected into a file and distributed as a # public keyring of FreeBSD developers that can # easily be imported into PGP/GPG. # # ------------------------------------------------------------------------ .PATH: ${.CURDIR}/../../share/sgml/glossary MAINTAINER= doc@FreeBSD.org DOC?= book FORMATS?= html-split HAS_INDEX= true INSTALL_COMPRESSED?= gz INSTALL_ONLY_COMPRESSED?= IMAGES_EN = advanced-networking/isdn-bus.eps IMAGES_EN+= advanced-networking/isdn-twisted-pair.eps IMAGES_EN+= advanced-networking/natd.eps IMAGES_EN+= advanced-networking/net-routing.pic IMAGES_EN+= advanced-networking/static-routes.pic IMAGES_EN+= install/adduser1.scr IMAGES_EN+= install/adduser2.scr IMAGES_EN+= install/adduser3.scr IMAGES_EN+= install/boot-mgr.scr IMAGES_EN+= install/console-saver1.scr IMAGES_EN+= install/console-saver2.scr IMAGES_EN+= install/console-saver3.scr IMAGES_EN+= install/console-saver4.scr IMAGES_EN+= install/desktop.scr IMAGES_EN+= install/disklabel-auto.scr IMAGES_EN+= install/disklabel-ed1.scr IMAGES_EN+= install/disklabel-ed2.scr IMAGES_EN+= install/disklabel-fs.scr IMAGES_EN+= install/disklabel-root1.scr IMAGES_EN+= install/disklabel-root2.scr IMAGES_EN+= install/disklabel-root3.scr IMAGES_EN+= install/disk-layout.eps IMAGES_EN+= install/dist-set.scr IMAGES_EN+= install/dist-set2.scr IMAGES_EN+= install/docmenu1.scr IMAGES_EN+= install/ed0-conf.scr IMAGES_EN+= install/ed0-conf2.scr IMAGES_EN+= install/edit-inetd-conf.scr IMAGES_EN+= install/fdisk-drive1.scr IMAGES_EN+= install/fdisk-drive2.scr IMAGES_EN+= install/fdisk-edit1.scr IMAGES_EN+= install/fdisk-edit2.scr IMAGES_EN+= install/ftp-anon1.scr IMAGES_EN+= install/ftp-anon2.scr IMAGES_EN+= install/hdwrconf.scr IMAGES_EN+= install/keymap.scr IMAGES_EN+= install/main1.scr IMAGES_EN+= install/mainexit.scr IMAGES_EN+= install/main-std.scr IMAGES_EN+= install/main-options.scr IMAGES_EN+= install/main-doc.scr IMAGES_EN+= install/main-keymap.scr IMAGES_EN+= install/media.scr IMAGES_EN+= install/mouse1.scr IMAGES_EN+= install/mouse2.scr IMAGES_EN+= install/mouse3.scr IMAGES_EN+= install/mouse4.scr IMAGES_EN+= install/mouse5.scr IMAGES_EN+= install/mouse6.scr IMAGES_EN+= install/mta-main.scr IMAGES_EN+= install/net-config-menu1.scr IMAGES_EN+= install/net-config-menu2.scr IMAGES_EN+= install/nfs-server-edit.scr IMAGES_EN+= install/ntp-config.scr IMAGES_EN+= install/options.scr IMAGES_EN+= install/pkg-cat.scr IMAGES_EN+= install/pkg-confirm.scr IMAGES_EN+= install/pkg-install.scr IMAGES_EN+= install/pkg-sel.scr IMAGES_EN+= install/probstart.scr IMAGES_EN+= install/routed.scr IMAGES_EN+= install/security.scr IMAGES_EN+= install/sysinstall-exit.scr IMAGES_EN+= install/timezone1.scr IMAGES_EN+= install/timezone2.scr IMAGES_EN+= install/timezone3.scr IMAGES_EN+= install/userconfig.scr IMAGES_EN+= install/userconfig2.scr IMAGES_EN+= install/xf86setup.scr IMAGES_EN+= mail/mutt1.scr IMAGES_EN+= mail/mutt2.scr IMAGES_EN+= mail/mutt3.scr IMAGES_EN+= mail/pine1.scr IMAGES_EN+= mail/pine2.scr IMAGES_EN+= mail/pine3.scr IMAGES_EN+= mail/pine4.scr IMAGES_EN+= mail/pine5.scr IMAGES_EN+= install/example-dir1.eps IMAGES_EN+= install/example-dir2.eps IMAGES_EN+= install/example-dir3.eps IMAGES_EN+= install/example-dir4.eps IMAGES_EN+= install/example-dir5.eps IMAGES_EN+= security/ipsec-network.pic IMAGES_EN+= security/ipsec-crypt-pkt.pic IMAGES_EN+= security/ipsec-encap-pkt.pic IMAGES_EN+= security/ipsec-out-pkt.pic IMAGES_EN+= vinum/vinum-concat.pic IMAGES_EN+= vinum/vinum-mirrored-vol.pic IMAGES_EN+= vinum/vinum-raid10-vol.pic IMAGES_EN+= vinum/vinum-raid5-org.pic IMAGES_EN+= vinum/vinum-simple-vol.pic IMAGES_EN+= vinum/vinum-striped-vol.pic IMAGES_EN+= vinum/vinum-striped.pic # Images from the cross-document image library IMAGES_LIB= callouts/1.png IMAGES_LIB+= callouts/2.png IMAGES_LIB+= callouts/3.png IMAGES_LIB+= callouts/4.png IMAGES_LIB+= callouts/5.png IMAGES_LIB+= callouts/6.png IMAGES_LIB+= callouts/7.png IMAGES_LIB+= callouts/8.png IMAGES_LIB+= callouts/9.png IMAGES_LIB+= callouts/10.png # # SRCS lists the individual SGML files that make up the document. Changes # to any of these files will force a rebuild # # SGML content +SRCS+= audit/chapter.sgml SRCS+= book.sgml SRCS+= colophon.sgml SRCS+= freebsd-glossary.sgml SRCS+= advanced-networking/chapter.sgml SRCS+= basics/chapter.sgml SRCS+= bibliography/chapter.sgml SRCS+= boot/chapter.sgml SRCS+= config/chapter.sgml SRCS+= cutting-edge/chapter.sgml SRCS+= desktop/chapter.sgml SRCS+= disks/chapter.sgml SRCS+= eresources/chapter.sgml SRCS+= firewalls/chapter.sgml +SRCS+= geom/chapter.sgml SRCS+= install/chapter.sgml SRCS+= introduction/chapter.sgml SRCS+= kernelconfig/chapter.sgml SRCS+= l10n/chapter.sgml SRCS+= linuxemu/chapter.sgml SRCS+= mac/chapter.sgml SRCS+= mail/chapter.sgml SRCS+= mirrors/chapter.sgml SRCS+= multimedia/chapter.sgml SRCS+= network-servers/chapter.sgml SRCS+= pgpkeys/chapter.sgml SRCS+= ports/chapter.sgml SRCS+= ppp-and-slip/chapter.sgml SRCS+= preface/preface.sgml SRCS+= printing/chapter.sgml SRCS+= security/chapter.sgml SRCS+= serialcomms/chapter.sgml SRCS+= users/chapter.sgml SRCS+= vinum/chapter.sgml SRCS+= x11/chapter.sgml # Entities SRCS+= chapters.ent SYMLINKS= ${DESTDIR} index.html handbook.html # Turn on all the chapters. CHAPTERS?= ${SRCS:M*chapter.sgml} SGMLFLAGS+= ${CHAPTERS:S/\/chapter.sgml//:S/^/-i chap./} SGMLFLAGS+= -i chap.freebsd-glossary # XXX The Handbook build currently overflows some internal, hardcoded # limits in pdftex. Until we split the Handbook up, build the PDF # version using ps2pdf instead of pdftex. PS2PDF?= ${PREFIX}/bin/ps2pdf book.tex-pdf: ${TOUCH} book.tex-pdf book.pdf: book.ps ${PS2PDF} book.ps book.pdf pgpkeyring: pgpkeys/chapter.sgml @${JADE} -V nochunks ${OTHERFLAGS} ${JADEOPTS} -d ${DSLPGP} -t sgml ${MASTERDOC} # # Handbook-specific variables # .if defined(WITH_PGPKEYS) JADEFLAGS+= -V withpgpkeys .endif .for p in ftp cvsup SRCS+= mirrors.sgml.${p}.inc CLEANFILES+= mirrors.sgml.${p}.inc CLEANFILES+= mirrors.sgml.${p}.inc.tmp .endfor SRCS+= eresources.sgml.www.inc CLEANFILES+= eresources.sgml.www.inc CLEANFILES+= eresources.sgml.www.inc.tmp URL_RELPREFIX?= ../../../.. DOC_PREFIX?= ${.CURDIR}/../../.. .include "${DOC_PREFIX}/share/mk/doc.project.mk" .for p in ftp cvsup mirrors.sgml.${p}.inc: ${XML_MIRRORS} ${XSL_MIRRORS} ${XSLTPROC} ${XSLTPROCOPTS} \ -o $@.tmp \ --param 'type' "'$p'" \ --param 'proto' "'$p'" \ --param 'target' "'handbook/mirrors/chapter.sgml'" \ ${XSL_MIRRORS} ${XML_MIRRORS} ${SED} -e 's,<\([^ >]*\)\([^>]*\)/>,<\1\2>,;s,,,'\ < $@.tmp > $@ || (${RM} -f $@ && false) ${RM} -f $@.tmp .endfor eresources.sgml.www.inc: ${XML_MIRRORS} ${XSL_MIRRORS} ${XSLTPROC} ${XSLTPROCOPTS} \ -o $@.tmp \ --param 'type' "'www'" \ --param 'proto' "'http'" \ --param 'target' "'handbook/eresources/chapter.sgml'" \ ${XSL_MIRRORS} ${XML_MIRRORS} ${SED} -e 's,<\([^ >]*\)\([^>]*\)/>,<\1\2>,;s,,,'\ < $@.tmp > $@ || (${RM} -f $@ && false) ${RM} -f $@.tmp diff --git a/en_US.ISO8859-1/books/handbook/audit/Makefile b/en_US.ISO8859-1/books/handbook/audit/Makefile new file mode 100644 index 0000000000..84cb9b04ee --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/audit/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= audit/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/audit/chapter.sgml b/en_US.ISO8859-1/books/handbook/audit/chapter.sgml new file mode 100644 index 0000000000..8e2db85afe --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/audit/chapter.sgml @@ -0,0 +1,530 @@ + + + + + + + + + + + Tom + Rhodes + Written by + + + + + Kernel Event Auditing + + + Synopsis + + AUDIT + + Kernel Event Auditing + MAC + + + The &os; 6.0 operating system release has included + support for Event Auditing based on the &posix;.1e draft and + the &sun; BSM implementation. Event auditing + permits the selective logging of security-relevant system events + for the purposes of system analysis, system monitoring, and + security evaluation. + + This chapter will focus mainly on the installation and + configuration of Event Auditing. Explanation of audit policies, + and an example configuration will be provided for the + convenience of the reader. + + After reading this chapter, you will know: + + + + What Event Auditing is and how it works. + + + + How to configure Event Auditing on &os; for users + and processes. + + + + Before reading this chapter, you should: + + + + Understand &unix; and &os; basics + (). + + + + Be familiar with the basics of kernel + configuration/compilation + (). + + + + Have some familiarity with security and how it + pertains to &os; (). + + + + + Event auditing can generate a great deal of log file + data, exceeding gigabytes a week in some configurations. An administrator + should read this chapter in its entirety to avoid possible + self inflicted DoS attacks due to improper + configuration. + + + The implementation of Event Auditing in &os; is similar to + that of the &sun; Basic Security Module, or BSM + library. Thus, the configuration is almost completely + interchangeable with &solaris; and Darwin operating systems. + + + + Key Terms - Words to Know + + Before reading this chapter, a few key terms must be + explained. This is intended to clear up any confusion that + may occur and to avoid the abrupt introduction of new terms + and information. + + + + class: A class specifies the category + different actions the system are placed in. For example, + use of &man.login.1; could be placed in a class. + + + + event: An event could be considered + an action taken on the system. Creating a file would be + an event. + + + + record: A record is a log or a note + about a specific action. + + + + prefix: A prefix is considered to + be the configuration element used to toggle auditing for + success and failed events. + + + + + + Installing Audit Support + + Support for Event Auditing should have been installed with + the normal installworld process. An + administrator may confirm this by viewing the contents + of /etc/security. Files + beginning with the word audit should be present. + For example, audit_event. + + In-kernel support for the framework must also exist. This + may be done by adding the following lines to the local kernel + configuration file: + + options AUDIT + + Rebuild and reinstall + the kernel via the normal process explained in + . + + Once completed, enable the audit daemon by adding the + following line to &man.rc.conf.5;: + + auditd_enable="YES" + + Functionality not provided by the default may be added + here with the option. + + + + Audit Configuration + + By default, all configuration is done within the realm of + /etc/security and the + files contained within. The following files must be present + before the audit daemon is started: + + + + audit_class - Contains the + definitions of the audit classes. + + + + audit_control - Controls aspects + of the audit subsystem, such as default audit classes, + minimum disk space to leave on the audit log volume, + etc. + + + + audit_event - Defines the kernel + audit events. These map, mostly, to system calls. + + + + audit_user - The events to audit + for individual users. A user name does not need to appear + in here. + + + + audit_warn - A shell script + used by auditd to form warning messages. + + + + If these files do not exist, for whatever reason, they can + be installed easily by issuing the following commands: + + &prompt.root; cd /usr/src/contrib/bsm/etc && make install + + + Audit File Syntax + + The configuration file syntax is rather arcane, albeit easy + to work with. One thing an administrator must be leery about + is overriding system defaults. This could create potential + openings for audit data to not be collected properly. + + The audit subsystem will accept both the short name and + long name with regards to configuration syntax. A syntax + map has been included below. + + The following list contains all supported audit + classes: + + + + - all - All + audit flags set. + + + + - administrative + - Administrative actions performed on the system as a + whole. + + + + - application - + Application defined action. + + + + - file_close - + Audit calls to the close system + call. + + + + - exec - Audit + program or utility execution. + + + + - file_attr_acc + - Audit the access of object attributes such as + &man.stat.1;, &man.pathconf.2; and similar events. + + + + - file_creation + - Audit events where a file is created as a result. + + + + - file_deletion + - Audit events where file deletion occurrs. + + + + - file_attr_mod + - Audit events where file attribute modification occurs, + such as &man.chown.8;, &man.chflags.1;, &man.flock.2;, + etc. + + + + - file_read + - Audit events in which data is read, files are opened for + reading, etc. + + + + - file_write - + Audit events in which data is written, files are written + or modified, etc. + + + + - ioctl - Audit + use of the &man.ioctl.2; system call. + + + + - ipc - Audit + System V IPC operations. + + + + - login_logout - + Audit &man.login.1; and &man.logout.1; events occurring + on the system. + + + + - non_attrib - + Audit non-attributable events. + + + + - no_class - + Null class used to disable event auditing. + + + + - network - + Audit events related to network actions, such as + &man.connect.2; and &man.accept.2;. + + + + - other - + Audit miscellaneous events. + + + + - process - + Audit process operations, such as &man.exec.3; and + &man.exit.3;. + + + + - tfm - + I HAVE NO CLUE! + + + + Following is a list of all supported audit prefixes: + + + + none - Audit both the success + or failure of an event. For example, just listing a + class will result in the auditing of both success and + failure. + + + + + - Audit successful events + only. + + + + - - Audit failed events + only. + + + + + Using the class with either the + positive or negative prefix can generate a large amount + of data at an extremely rapid rate. + + + Extra prefixes used to modify the default configuration + values: + + + + ^- - Disable auditing of failed events. + + + + ^+ - Enable auditing of successful events. + + + + ^ - Disable auditing of both successful and failed + events. + + + + + + Configuration Files + + Configuration is set in only two files, the first being + audit_control and + audit_user being the second. The first + is system-wide, controlling every aspect of event auditing + in the system. The latter may be used for fine grained user + auditing. + + + The <filename>audit_control</filename> File + + The audit_control contains some basic + defaults that the administrator may wish to modify. Perhaps + even set some new ones. Viewing the contents of this file, + we see the following: + + dir:/var/audit +flags:lo,ad,-all,^-fa,^-fc,^-cl +minfree:20 +naflags:lo + + The is used to set the default + directory where audit logs are stored. + + The is used to set the system-wide + defaults. The current setting, + audits all system + &man.login.1; and &man.logout.1; actions, all administrator + actions, all failed events in the system, and finally disable + auditing of failed attempts for , + , and . Even though + the turned on the auditing of all + failed attempts, the prefix will override + that for the latter options. + + Notice that the previous paragraph shows the file is + read from left to right. As such, values further on the + right side may override a previous value specified to + its left. + + The option defines the minimum + percentage of free space for audit file systems. This + relates to the file system where audit logs are stored. + For example, if the specifies + /var/audit and + is set to twenty (20), warning + messages will be generated when the + /var file system grows + to eighty (80) percent full. + + The option specifies audit + flags to be considered non attributable; i.e.: classes of + events which cannot be attributed to a specific user + on the system. This can be overridden with the + audit_user configuration file. + + + + The <filename>audit_user</filename> File + + The audit_user permits the + administrator to map audit specific events to directly + to users. This adds a finer-grained control mechanism + for all system users. + + The following is the defaults currently placed in + the audit_user file: + + root:lo:no +audit:fc:no + + Notice how the default is to audit all cases of + login/logout + and disable auditing of all other actions for + root. This configuration + also audits all file creation and disables all + other auditing for the audit + user. While event auditing does not require a special + user exist, some configurations, specifically environments + making use of MAC may require it. + + + + + + Event Audit Administration + + Events from the auditd daemon cannot + be altered or read in plain text. Data is stored and accessed + in a method similar to that of &man.ktrace.1; and &man.kdump.1, + that is, they may only be viewed by dumping them using the + praudit or auditreduce + utilities. + + There are two utilities because of different requirements. + For example, the praudit will dump the entire + contents of a specified audit log in plain text. To dump an + audit log in its entirety, use: + + &prompt.root; praudit /var/audit/AUDITFILE + + Where AUDITFILE is the audit log + of viewing choice. Since audit logs may contain enormous + amounts of data, an administrator may prefer to select records + for specific users. This is made possible with the following + command, where trhodes is the user of + choice: + + &prompt.root; auditreduce -e trhodes /var/audit/AUDITFILE + + This will select all audit records produced by the user + trhodes stored in the + AUDITFILE file. + + There are several other options available for reading audit + records, see the aforementioned command's manual pages for + a more in depth explination. + + + Rotating Audit Log Files + + Manually rotating audit log files will cause great + havoc within the system. Therefore, adding a line to + &man.newsyslog.conf.5; will provide no usefulness. So how + are the logs to be rotated? Sending the appropriate flag + to the audit utility will shut down + event auditing and safely rotate. The following command + should handle everything for an administrator: + + &prompt.root; audit -n + + + If the auditd daemon is not currently + running, the previous command will fail and an error message + will be produced. + + + Adding the following line to + /etc/crontab will force the rotation + every twelve hours from &man.cron.8;: + + * */12 * * * root /usr/sbin/audit -n + + Remember to reinstall the crontab + file. Otherwise the rotation will never occur. + + + diff --git a/en_US.ISO8859-1/books/handbook/book.sgml b/en_US.ISO8859-1/books/handbook/book.sgml index 069a8afe5d..407d0425fb 100644 --- a/en_US.ISO8859-1/books/handbook/book.sgml +++ b/en_US.ISO8859-1/books/handbook/book.sgml @@ -1,336 +1,338 @@ %books.ent; %chapters; %txtfiles; + %pgpkeys; ]> FreeBSD Handbook The FreeBSD Documentation Project February 1999 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 The FreeBSD Documentation Project &bookinfo.legalnotice; &tm-attrib.freebsd; &tm-attrib.3com; &tm-attrib.3ware; &tm-attrib.arm; &tm-attrib.adaptec; &tm-attrib.adobe; &tm-attrib.apple; &tm-attrib.corel; &tm-attrib.creative; &tm-attrib.cvsup; &tm-attrib.heidelberger; &tm-attrib.ibm; &tm-attrib.ieee; &tm-attrib.intel; &tm-attrib.intuit; &tm-attrib.linux; &tm-attrib.lsilogic; &tm-attrib.m-systems; &tm-attrib.macromedia; &tm-attrib.microsoft; &tm-attrib.netscape; &tm-attrib.nexthop; &tm-attrib.opengroup; &tm-attrib.oracle; &tm-attrib.powerquest; &tm-attrib.realnetworks; &tm-attrib.redhat; &tm-attrib.sap; &tm-attrib.sun; &tm-attrib.symantec; &tm-attrib.themathworks; &tm-attrib.thomson; &tm-attrib.usrobotics; &tm-attrib.vmware; &tm-attrib.waterloomaple; &tm-attrib.wolframresearch; &tm-attrib.xfree86; &tm-attrib.xiph; &tm-attrib.general; Welcome to FreeBSD! This handbook covers the installation and day to day use of FreeBSD &rel2.current;-RELEASE and FreeBSD &rel.current;-RELEASE. This manual is a work in progress and is the work of many individuals. Many sections do not yet exist and some of those that do exist need to be updated. If you are interested in helping with this project, send email to the &a.doc;. The latest version of this document is always available from the FreeBSD web site. It may also be downloaded in a variety of formats and compression options from the FreeBSD FTP server or one of the numerous mirror sites. If you would prefer to have a hard copy of the handbook, you can purchase one at the FreeBSD Mall. You may also want to search the handbook. &chap.preface; Getting Started This part of the FreeBSD Handbook is for users and administrators who are new to FreeBSD. These chapters: Introduce you to FreeBSD. Guide you through the installation process. Teach you &unix; basics and fundamentals. Show you how to install the wealth of third party applications available for FreeBSD. Introduce you to X, the &unix; windowing system, and detail how to configure a desktop environment that makes you more productive. We have tried to keep the number of forward references in the text to a minimum so that you can read this section of the Handbook from front to back with the minimum page flipping required. Common Tasks Now that the basics have been covered, this part of the FreeBSD Handbook will discuss some frequently used features of FreeBSD. These chapters: Introduce you to popular and useful desktop applications: browsers, productivity tools, document viewers, etc. Introduce you to a number of multimedia tools available for FreeBSD. Explain the process of building a customized FreeBSD kernel, to enable extra functionality on your system. Describe the print system in detail, both for desktop and network-connected printer setups. Show you how to run Linux applications on your FreeBSD system. Some of these chapters recommend that you do some prior reading, and this is noted in the synopsis at the beginning of each chapter. System Administration The remaining chapters of the FreeBSD Handbook cover all aspects of FreeBSD system administration. Each chapter starts by describing what you will learn as a result of reading the chapter, and also details what you are expected to know before tackling the material. These chapters are designed to be read when you need the information. You do not have to read them in any particular order, nor do you need to read all of them before you can begin using FreeBSD. + Network Communication FreeBSD is one of the most widely deployed operating systems for high performance network servers. The chapters in this part cover: Serial communication PPP and PPP over Ethernet Electronic Mail Running Network Servers Firewalls Other Advanced Networking Topics These chapters are designed to be read when you need the information. You do not have to read them in any particular order, nor do you need to read all of them before you can begin using FreeBSD in a network environment. Appendices &chap.colophon; diff --git a/en_US.ISO8859-1/books/handbook/chapters.ent b/en_US.ISO8859-1/books/handbook/chapters.ent index 6585365fd0..9d94f16bb8 100644 --- a/en_US.ISO8859-1/books/handbook/chapters.ent +++ b/en_US.ISO8859-1/books/handbook/chapters.ent @@ -1,57 +1,58 @@ + diff --git a/en_US.ISO8859-1/books/handbook/geom/Makefile b/en_US.ISO8859-1/books/handbook/geom/Makefile new file mode 100644 index 0000000000..59e5759cdc --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/geom/Makefile @@ -0,0 +1,15 @@ +# +# Build the Handbook with just the content from this chapter. +# +# $FreeBSD$ +# + +CHAPTERS= geom/chapter.sgml + +VPATH= .. + +MASTERDOC= ${.CURDIR}/../${DOC}.${DOCBOOKSUFFIX} + +DOC_PREFIX?= ${.CURDIR}/../../../.. + +.include "../Makefile" diff --git a/en_US.ISO8859-1/books/handbook/geom/chapter.sgml b/en_US.ISO8859-1/books/handbook/geom/chapter.sgml new file mode 100644 index 0000000000..202a2ff7e9 --- /dev/null +++ b/en_US.ISO8859-1/books/handbook/geom/chapter.sgml @@ -0,0 +1,376 @@ + + + + + + + Tom + Rhodes + Written by + + + + + GEOM: Modular Disk Transformation Framework + + + Synopsis + + + GEOM + + + GEOM Disk Framework + GEOM + + + This chapter covers the use of disks under the new GEOM + framework in &os;. This includes the major + RAID control utilities which use the + framework for configuration. This chapter will not go + into in depth discussion on how GEOM handles or controls + I/O, the underlying subsystem, or code. This information + is provided through the &man.geom.4; manual page and its various + SEE ALSO references. This chapter is also not a definitive guide + to RAID configurations. Only GEOM + supported RAID classifications will be + discussed. + + After reading this chapter, you will know: + + + + What type of RAID support is available + through GEOM. + + + + How to use the base base utilities to configure, maintain + and manipulate the various RAID + levels. + + + + How to mirror, stripe, encrypt, and remotely connect disk + devices through GEOM. + + + + How to troubleshoot disks attached to the GEOM + framework. + + + + Before reading this chapter, you should: + + + + Understand how &os; treats disk devices + (). + + Know how to configure and install a new &os; kernel + (). + + + + + + GEOM Introduction + + GEOM permits access and control to classes — Master Boot + Records, BSD labels, etc — through the + use of providers, or the special files in + /dev. Supporting various + software RAID configurations, GEOM will + transparently provide access to the operating system and + operating system utilities. + + + + RAID0 - Striping + + + GEOM + + + Stripping + + + Striping is a method used to combine several disk drives into + a single volume. In many cases, this is done through the use of + hardware controllers supporting all variants of disks, + SCSI, SATA, + and ATA. The GEOM disk subsystem provides + software support for RAID1, also known as + disk striping. + + Some cases have this volume, comprised of several disks, as a + separate file system for backups, data storage for users; + however, in other cases still, this volume may hold the root, or + / partition and the system + will boot from it. Both will be described herein. + + To stripe several ATA disks, of the same + size of course, load the geom_stripe + module: + + &prompt.root; kldload geom_stripe.ko + + The module should now be loaded and visible from the output of + kldstat. Now to combine the disks. Ensure + that a mount point exists, if this volume will become a root + partition then temporarily use + /mnt. Otherwise, for the + purpose of our examples, this volume will reside at the + /home mount point. This + process may be complicated if users already exist on the system. + If so, assume the volume will reside on + /data. + + Begin by selecting the disks which will be striped. Our + scenario has two unused, unpartitioned ATA + disks: /dev/ad2 and + /dev/ad3. The module has been loaded and + our disks selected, we will now create the stripe device: + + &prompt.root; gstripe label -v st0 /dev/ad2 /dev/ad3 + + A message should be returned explaining that meta data has + been stored on the devices. The file system must now be created + on the device. If this volume is to be used for system + initialization, the following command must be issued before the + file system is created: + + &prompt.root; fdisk -vBI /dev/stripe/st0 + + Create a partition table on the new volume: + + &prompt.root; bsdlabel -wB /dev/stripe/st0 + + This process should have created two other devices in the + /dev/stripe directory in + addition to the st0 device. Those include + st0a and st0c. Next a + file system must be created on the device using + newfs: + + &prompt.root; newfs -U /dev/stripe/st0a + + Many numbers will glide across the screen, and after a few + seconds, the process will be complete. The volume has been + created and is ready to be hung from its mount + point: + + &prompt.root; mount /dev/stripe/st0a /home + + Place the volume information in + /etc/fstab file: + + &prompt.root; echo "/dev/stripe/st0a /home ufs rw 2 2" \ + >> /etc/fstab + + And load the module during system initialization: + + &prompt.root; echo 'geom_stripe_load="YES" >> /boot/loader.conf + + From here on, all users will have their data stored on the + striped volume comprised of the disks concatenated in the + beginning. + + + + RAID1 - Mirroring + + + GEOM + + + Disk Mirroring + + + Mirroring is a technology used by many corporations and home + users to back up data without interruption. When a mirror exists, + it simply means that diskB replicates diskA. Or, perhaps diskC+D + replicates diskA+B. Regardless of the disk configuration, the + important aspect isthat information on one disk or partition is + being replicated. Later, that information could be more easily + restored, backed up without causing service or access + interruption, and even be physically stored in a data + safe. + + To begin, ensure the system has two disk drives of equal size, + this exorcise assumes they are direct access (&man.da.4;) + SCSI disks. + + Begin by installing &os; on the first disk with only two + partitions. One should be a swap partition, double the + RAM size and all remaining space devoted to + the root (/ file system. + It is possible to have separate partitions for other mount points; + however, this will increase the difficulty level ten fold due to + manual alteration of the &man.bsdlabel.8; and &man.fdisk.8; + settings. + + Reboot and wait for the system to fully initialize. Once this + process has completed, log in as the root + user. + + Create the /dev/mirror/gm device and link + it with /dev/da1: + + &prompt.root; gmirror label -vnb round-robin gm0 /dev/da1 + + + This command should have created the + gm0, gm0s1, + gm0s1a, and gm0s1c + device nodes under the + /dev/mirror + directory. + + + Initialize GEOM, this will load the + /boot/kernel/geom_mirror.ko kernel + module: + + &prompt.root; geom load + + Install generic fdisk label and boot code + to newly created gm0 device: + + &prompt.root; fdisk -vBI /dev/mirror/gm0 + + Now install generic bsdlabel + information: + + &prompt.root; bsdlabel -wB /dev/mirror/gm0s1 + + + If multiple slices and partitions exist, the flags for the + previous two commands will require alteration. They must match + the slice and partition size of the other disk. + + + Use the &man.newfs.8; utility to create a default file + system on the gm0s1a device node: + + &prompt.root; newfs -U /dev/mirror/gm0s1a + + This should have caused for the system to spit out some + information and a bunch of numbers. This is good, examine the + screen for any error messages and mount the device to the + /mnt mount point: + + &prompt.root mount /dev/mirror/gm0s1a /mnt + + Now move all data from the boot disk over to this new file + system. This example uses the &man.dump.8; and &man.restore.8; + commands; however, &man.dd.1; would also work with this scenario. + We skip using &man.tar.1; because it will not copy over the boot + code. Thus, failure would be guarenteed. + + &prompt.root; dump -L -0 -f- / |(cd /mnt && restore -r -v -f-) + + This must be done for each file system. Simply place the + appropriate file system in correct location when running the + aforementioned command. + + Now edit the replicated /mnt/etc/fstab + file and remove or comment out the swap file. Change the other + file system information to use the new disk. See the following + example: + + # Device Mountpoint FStype Options Dump Pass# +#/dev/da0s2b none swap sw 0 0 +/dev/mirror/gm0sa1 / ufs rw 1 1 + + Now create a boot.conf file on both the + current and new root partitions. This file will + help the system BIOS + boot the correct drive: + + &prompt.root; echo "1:da(1,a)/boot/loader" > /boot.config + + &prompt.root; echo "1:da(1,a)/boot/loader" > /mnt/boot.config + + + We have placed it on both root partitions to ensure proper + boot up. If for some reason the system cannot read from the + new root partition, a failsafe is available. + + + Now add the following line to + /boot/loader.conf: + + &prompt.root; echo 'geom_mirror_load="YES"' >> /boot/loader.conf + + This will instruct &man.loader.8; utility to load the + geom_mirror.ko during system + initialization. + + Reboot the system: + + &prompt.root; shutdown -r now + + If all has gone well, the system should have booted from the + gm0s1a device and a login + prompt should be waiting. If something went wrong, see review + the forthcoming troubleshooting section. Now add the + da0 disk to gm0 + device: + + &prompt.root; gmirror configure -a gm0 + gmirror insert gm0 /dev/da0 + + The flag tells &man.gmirror.8; to use + automatic synchronization, i.e.: mirror the disk writes + automatically. The manual page explains how to rebuild and + replace disks, although it uses data + in place of gm0. + + + Troubleshooting + + + System refuses to boot + + If the system boots up to a prompt similar to: + + ffs_mountroot: can't find rootvp +Root mount failed: 6 +mountroot> + + Reboot the machine using the power or reset button. At + the boot menu, select option six (6). This will drop the + system to a &man.loader.8; prompt. Load the kernel module + manually: + + OK? load geom_mirror.ko + OK? boot + + If this works then for whatever reason the module was not + being loaded properly. Place: + + options GEOM_MIRROR + + In the kernel configuration file, rebuild and reinstall. + That should remedy this issue. + + + + + +