path: root/usr/src/man/man4/wanboot.conf.4

'\" te
.\" Copyright (c) 2003, Sun Microsystems, Inc. All Rights Reserved.
.\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
.\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
.\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
.TH WANBOOT.CONF 4 "Nov 15, 2003"
.SH NAME
wanboot.conf \- repository for WANboot configuration data
.SH SYNOPSIS
.LP
.nf
\fB\fR\fB/etc/netboot/wanboot.conf\fR
.fi

.SH DESCRIPTION
.sp
.LP
The \fBwanboot.conf\fR file is set up by a system administrator for one or more
WANboot clients. The file contains information used to drive the WANboot
process. The CGI program that serves up the bootstrap (wanboot) and the boot
and root filesystems use information contained in the file to determine file
paths, encryption and signing policies, and other characteristics of the
operating environment.
.sp
.LP
A copy of \fBwanboot.conf\fR is incorporated in the boot filesystem that is
transmitted to the client. This is used by the bootstrap (wanboot) to determine
SSL authentication policy, and other security conditions.
.sp
.LP
You should use the \fBbootconfchk\fR(1M) utility to check the format and
content of a \fBwanboot.conf\fR file prior to deployment.
.SH FILE FORMAT
.sp
.LP
Entries in \fBwanboot.conf\fR are written one per line; an entry cannot be
continued onto another line. Blank lines are ignored, as is anything following
a hash mark character (\fB#\fR), which allows you to insert comments.
.sp
.LP
Each non-blank, non-comment line must take the form:
.sp
.in +2
.nf
\fIparameter\fR=\fIvalue\fR
.fi
.in -2
.sp

.sp
.LP
where \fIvalue\fR is terminated by the end-of-line, a space, or the hash mark
character. The value can be quoted if it contains a space or a hash mark, using
single or double quotes.
.sp
.LP
The parameters currently supported and their meanings are as follows:
.sp
.ne 2
.na
\fB\fIboot_file\fR\fR
.ad
.RS 25n
Specifies the path of the bootstrap file relative to the directory from which
the web server serves files. This parameter must be given if the bootstrap file
(wanboot) is to be served via HTTP, and must be specified with a leading slash
(\fB/\fR).
.RE

.sp
.ne 2
.na
\fB\fIroot_server\fR\fR
.ad
.RS 25n
Specifies the location of the CGI program that will serve up the information
about the root filesystem that will be transmitted to the client. If present,
the value must be a URL in one of the following forms:
.sp
.in +2
.nf
http://\fIhost\fR:\fIport\fR/\fIsome_path\fR/\fIwanboot-cgi\fR
https://\fIhost\fR:\fIport\fR/\fIsome_path\fR/\fIwanboot-cgi\fR
.fi
.in -2
.sp

where \fBhttp\fR specifies insecure download of the root filesystem;
\fBhttps\fR specifies secure download of the root filesystem; \fIhost\fR is the
name of the system which will serve the root filesystem; \fIport\fR is the port
through which the web server will serve the root filesystem image;
\fIsome-path\fR is the directory which contains the \fIwanboot-cgi\fR CGI
program which will serve information about the root filesystem. For example:
.sp
.in +2
.nf
http://webserver:8080/cgi-bin/wanboot-cgi
.fi
.in -2
.sp

.RE

.sp
.ne 2
.na
\fB\fIroot_file\fR\fR
.ad
.RS 25n
Specifies the path of the root filesystem image relative to the directory from
which the web server serves files. This parameter must be given if the root
filesystem is to be served by means of HTTP, and must be specified with a
leading \fB/\fR.
.RE

.sp
.ne 2
.na
\fB\fIsignature_type\fR\fR
.ad
.RS 25n
Specifies the signing algorithm to be used when signing the bootstrap (that is,
wanboot), the boot filesystem, and the root filesystem (assuming the last is
not being sent using secure HTTP), prior to transmission to the client. If
absent, or the value is empty, no signing will be performed. If present, its
value must be: \fBsha1\fR.
.sp
If \fIsignature_type\fR is set, the client system being booted must also be
setup with a client key for that algorithm.
.RE

.sp
.ne 2
.na
\fB\fIencryption_type\fR\fR
.ad
.RS 25n
Specifies the encryption algorithm to be used when encrypting the boot
filesystem prior to transmission to the client. If absent, or the value is
empty, no encryption of the boot filesystem will be performed. If present, its
value must be one of: \fB3des\fR or \fBaes\fR.
.sp
If \fIencryption_type\fR is set to one of the above algorithms, then the client
system being booted must also be setup with a client key for that algorithm and
a non-empty \fIencryption_type\fR must also be specified.
.RE

.sp
.ne 2
.na
\fB\fIserver_authentication\fR\fR
.ad
.RS 25n
Specifies whether server authentication should be requested during SSL
connection setup. If absent, or the value is empty, server authentication will
not be requested. If present, its value must be one of: \fByes\fR or \fBno\fR.
.RE

.sp
.ne 2
.na
\fB\fIclient_authentication\fR\fR
.ad
.RS 25n
Specifies whether client authentication should be requested during SSL
coonection setup. If absent, or the value is empty, client authentication will
not be requested. If present, its value must be one of: \fByes\fR or \fBno\fR.
.sp
If client_authentication is \fByes\fR, then encryption and signing algorithms
must also be specified, the URL scheme in \fIroot_server\fR must be
\fBhttps\fR, and server_authentication must also be \fByes\fR.
.RE

.sp
.ne 2
.na
\fB\fIresolve_hosts\fR\fR
.ad
.RS 25n
Used to specify any host names that might need to be resolved for the client
system. Host names appearing in URLs in \fBwanboot.conf\fR and any discovered
in certificates associated with the client will automatically be resolved and
do not need to be specified here. The value should be a comma-separated list of
host names.
.sp
A typical use of this parameter would be to name hosts used by the installer
that differ from any of those used by the bootstrap.
.RE

.sp
.ne 2
.na
\fB\fIboot_logger\fR\fR
.ad
.RS 25n
Specifies the URL of a system to which logging messages will be sent. If
absent, or the value is empty, then logging will be to the system console only.
If present it must specify a URL in one of the following forms:
.sp

.sp
.in +2
.nf
http://\fIhost\fR:\fIport\fR/\fIsome_path\fR/\fIbootlog-cgi\fR
https://\fIhost\fR:\fIport\fR/\fIsome_path\fR/\fIbootlog-cgi\fR
.fi
.in -2
.sp

where the constituent parts are as defined for \fIroot_server\fR, above.
.sp
Logging can be insecure or secure.
.RE

.sp
.ne 2
.na
\fB\fIsystem_conf\fR\fR
.ad
.RS 25n
Specifies the name of a file in the \fB/etc/netboot\fR hierarchy that will be
incorporated in the boot filesystem named \fBsystem.conf\fR and which is
intended for use by the system startup scripts only.
.RE

.SH EXAMPLES
.LP
\fBExample 1 \fRSample \fB\fR File
.sp
.LP
The following is a sample \fBwanboot.conf\fR file:

.sp
.in +2
.nf
####################################################################
#
# Copyright 2003 Sun Microsystems, Inc.  All rights reserved.
# Use is subject to license terms.
#
#ident  "@(#)wanboot.conf       1.12    03/01/30 SMI"
#
####################################################################
# wanboot.conf(4): boot configuration file.
#
# Please consult wanboot.conf(4) for further information.  Note that
# this interface is "Evolving" as defined by attributes(5).
#
# Anything after a '#' is comment.  Values may be quoted (e.g. "val").
#
# <empty> means there is no value, i.e. null.  The absence of any
# parameter implies that it takes a default value (<empty> unless
# otherwise specified).
#
# <url> is of the form http://... or https://...
####################################################################

# The path of the bootstrap file (within htdocs) which is served up
# by wanboot-cgi(bootfile).
#
boot_file=/bootfiles/wanboot    # <absolute pathname>

# These are used by wanboot-cgi(bootfile|bootfs|rootfs) to determine
# whether boot_file or the bootfs is to be sent encrypted/signed, or
# root_file is to be sent signed; the client must be setup with the
# corresponding encryption/signature key(s) (which cannot be auto-
# matically verified).
#
# If an encryption_type is specified then a signature_type must also
# be specified.
#
encryption_type=3des            # 3des | aes | <empty>
signature_type=sha1             # sha1 | <empty>

# This is used by wanboot-cgi(bootfs) and WANboot to determine whether
# server authentication should be requested during SSL connection
# setup.
#
server_authentication=yes       # yes | no

# This is used by wanboot-cgi(bootfs) and wanboot to determine whether
# client authentication should be requested during SSL connection
# setup.  If client_authentication is "yes", then server_authentication
# must also be "yes".
#
client_authentication=yes       # yes | no


# wanboot-cgi(bootfs) will construct a hosts file which resolves any
# hostnames specified in any of the URLs in the wanboot.conf file,
# plus those found in certificates, etc.  The following parameter
# may be used to add additional mappings to the hosts file.
#
resolve_hosts=                  # <hostname>[,<hostname>*] | <empty>

# This is used to specify the URL of wanboot-cgi on the server on which
# the root_file exists, and used by wanboot to obtain the root server's
# URL; wanboot substitutes root_file for the pathname part of the URL.
# If the schema is http://... then the root_file will be signed if there
# is a non-empty signature_type.  If server_authentication is "yes", the
# schema must be https://...; otherwise it must be http://...
#
root_server=https://www.example.com:1234/cgi-bin/wanboot-cgi # <url> \e
   | <empty>

# This is used by wanboot-cgi(rootfs) to locate the path of the
# rootfs image (within htdocs) on the root_server.
#
root_file=/rootimages/miniroot  # <absolute pathname> | <empty>

# This is used by wanboot to determine the URL of the boot_logger
# (and whether logging traffic should be sent using http or https),
# or whether it should simply be sent to the console.
#
boot_logger=http://www.example.com:1234/cgi-bin/bootlog-cgi  # <url> \e
    | <empty>

# This is used by the system startup scripts.
#
system_conf=system.conf
.fi
.in -2
.sp

.SH ATTRIBUTES
.sp
.LP
See \fBattributes\fR(5) for descriptions of the following attributes:
.sp

.sp
.TS
box;
c | c
l | l .
ATTRIBUTE TYPE	ATTRIBUTE VALUE
_
Interface Stability	Evolving
.TE

.SH SEE ALSO
.sp
.LP
\fBbootconfchk\fR(1M), \fBattributes\fR(5)