From: Mark Huang <mlhuang@cs.princeton.edu>
Date: Mon, 24 Apr 2006 22:14:56 +0000 (+0000)
Subject: - add variable list as an appendix
X-Git-Tag: myplc-0_4-rc1~55
X-Git-Url: http://git.onelab.eu/?a=commitdiff_plain;h=f614fcee4a47845a79cd3b59f228d24989e9e084;p=myplc.git
- add variable list as an appendix
---
diff --git a/doc/Makefile b/doc/Makefile
index da88c87..0b30792 100644
--- a/doc/Makefile
+++ b/doc/Makefile
@@ -4,15 +4,19 @@
# Mark Huang <mlhuang@cs.princeton.edu>
# Copyright (C) 2006 The Trustees of Princeton University
#
-# $Id: Makefile,v 1.1 2006/04/12 21:21:36 mlhuang Exp $
+# $Id: Makefile,v 1.2 2006/04/13 15:11:38 mlhuang Exp $
#
vpath GenDoc.xsl ../../plc_www/doc
+vpath plc_config.xml ..
all: myplc.pdf
# Dependencies
-.myplc.xml.valid: architecture.eps architecture.png
+.myplc.xml.valid: architecture.eps architecture.png variables.xml
+
+variables.xml: variables.xsl plc_config.xml
+ xsltproc $(XSLFLAGS) --output $@ $^
# Validate the XML
.%.xml.valid: %.xml
@@ -39,7 +43,7 @@ endef
$(foreach format,$(FORMATS),$(eval $(call docbook2,$(format))))
docclean:
- rm -f $(patsubst %,*.%,$(FORMATS)) *.pdf .*.xml.valid
+ rm -f $(patsubst %,*.%,$(FORMATS)) *.pdf .*.xml.valid variables.xml
clean: docclean
diff --git a/doc/myplc.pdf b/doc/myplc.pdf
index 4417ef9..17e99a3 100644
Binary files a/doc/myplc.pdf and b/doc/myplc.pdf differ
diff --git a/doc/myplc.xml b/doc/myplc.xml
index 5fdfeb6..9c1a2e3 100644
--- a/doc/myplc.xml
+++ b/doc/myplc.xml
@@ -1,6 +1,8 @@
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+ <!ENTITY Variables SYSTEM "variables.xml">
+]>
<article>
<articleinfo>
<title>MyPLC User's Guide</title>
@@ -470,6 +472,19 @@ vserver pl_conf exec service pl_conf restart]]></programlisting>
</section>
</section>
+ <appendix>
+ <title>Configuration variables</title>
+
+ <para>Listed below is the set of standard configuration variables
+ and their default values, defined in the template
+ <filename>/etc/planetlab/default_config.xml</filename>. Additional
+ variables and their defaults may be defined in site-specific XML
+ templates that should be placed in
+ <filename>/etc/planetlab/configs/</filename>.</para>
+
+ &Variables;
+ </appendix>
+
<bibliography>
<title>Bibliography</title>
diff --git a/doc/variables.xml b/doc/variables.xml
new file mode 100644
index 0000000..8b3bf84
--- /dev/null
+++ b/doc/variables.xml
@@ -0,0 +1,555 @@
+<variablelist>
+ <varlistentry>
+ <term>PLC_NAME</term>
+ <listitem>
+ <para>
+ Type: string</para>
+ <para>
+ Default: PlanetLab Test</para>
+ <para>The name of this PLC installation. It is used in
+ the name of the default system site (e.g., PlanetLab Central)
+ and in the names of various administrative entities (e.g.,
+ PlanetLab Support).</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_SLICE_PREFIX</term>
+ <listitem>
+ <para>
+ Type: string</para>
+ <para>
+ Default: pl</para>
+ <para>The abbreviated name of this PLC
+ installation. It is used as the prefix for system slices
+ (e.g., pl_conf). Warning: Currently, this variable should
+ not be changed.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_ROOT_USER</term>
+ <listitem>
+ <para>
+ Type: email</para>
+ <para>
+ Default: root@localhost.localdomain</para>
+ <para>The name of the initial administrative
+ account. We recommend that this account be used only to create
+ additional accounts associated with real
+ administrators, then disabled.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_ROOT_PASSWORD</term>
+ <listitem>
+ <para>
+ Type: password</para>
+ <para>
+ Default: root</para>
+ <para>The password of the initial administrative
+ account. Also the password of the root account on the Boot
+ CD.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_ROOT_SSH_KEY_PUB</term>
+ <listitem>
+ <para>
+ Type: file</para>
+ <para>
+ Default: /etc/planetlab/root_ssh_key.pub</para>
+ <para>The SSH public key used to access the root
+ account on your nodes.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_ROOT_SSH_KEY</term>
+ <listitem>
+ <para>
+ Type: file</para>
+ <para>
+ Default: /etc/planetlab/root_ssh_key.rsa</para>
+ <para>The SSH private key used to access the root
+ account on your nodes.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_DEBUG_SSH_KEY_PUB</term>
+ <listitem>
+ <para>
+ Type: file</para>
+ <para>
+ Default: /etc/planetlab/debug_ssh_key.pub</para>
+ <para>The SSH public key used to access the root
+ account on your nodes when they are in Debug mode.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_DEBUG_SSH_KEY</term>
+ <listitem>
+ <para>
+ Type: file</para>
+ <para>
+ Default: /etc/planetlab/debug_ssh_key.rsa</para>
+ <para>The SSH private key used to access the root
+ account on your nodes when they are in Debug mode.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_ROOT_GPG_KEY_PUB</term>
+ <listitem>
+ <para>
+ Type: file</para>
+ <para>
+ Default: /etc/planetlab/pubring.gpg</para>
+ <para>The GPG public keyring used to sign the Boot
+ Manager and all node packages.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_ROOT_GPG_KEY</term>
+ <listitem>
+ <para>
+ Type: file</para>
+ <para>
+ Default: /etc/planetlab/secring.gpg</para>
+ <para>The SSH private key used to access the root
+ account on your nodes.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_NET_DNS1</term>
+ <listitem>
+ <para>
+ Type: ip</para>
+ <para>
+ Default: 128.112.136.10</para>
+ <para>Primary DNS server address.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_NET_DNS2</term>
+ <listitem>
+ <para>
+ Type: ip</para>
+ <para>
+ Default: 128.112.136.12</para>
+ <para>Secondary DNS server address.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_MAIL_ENABLED</term>
+ <listitem>
+ <para>
+ Type: boolean</para>
+ <para>
+ Default: false</para>
+ <para>Set to false to suppress all e-mail notifications
+ and warnings.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_MAIL_SUPPORT_ADDRESS</term>
+ <listitem>
+ <para>
+ Type: email</para>
+ <para>
+ Default: root+support@localhost.localdomain</para>
+ <para>This address is used for support
+ requests. Support requests may include traffic complaints,
+ security incident reporting, web site malfunctions, and
+ general requests for information. We recommend that the
+ address be aliased to a ticketing system such as Request
+ Tracker.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_MAIL_BOOT_ADDRESS</term>
+ <listitem>
+ <para>
+ Type: email</para>
+ <para>
+ Default: root+install-msgs@localhost.localdomain</para>
+ <para>The API will notify this address when a problem
+ occurs during node installation or boot.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_MAIL_SLICE_ADDRESS</term>
+ <listitem>
+ <para>
+ Type: email</para>
+ <para>
+ Default: root+SLICE@localhost.localdomain</para>
+ <para>This address template is used for sending
+ e-mail notifications to slices. SLICE will be replaced with
+ the name of the slice.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_DB_ENABLED</term>
+ <listitem>
+ <para>
+ Type: boolean</para>
+ <para>
+ Default: true</para>
+ <para>Enable the database server on this
+ machine.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_DB_TYPE</term>
+ <listitem>
+ <para>
+ Type: string</para>
+ <para>
+ Default: postgresql</para>
+ <para>The type of database server. Currently, only
+ postgresql is supported.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_DB_HOST</term>
+ <listitem>
+ <para>
+ Type: hostname</para>
+ <para>
+ Default: localhost</para>
+ <para>The fully qualified hostname or IP address of
+ the database server. This hostname must be resolvable and
+ reachable by the rest of your installation.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_DB_PORT</term>
+ <listitem>
+ <para>
+ Type: int</para>
+ <para>
+ Default: 5432</para>
+ <para>The TCP port number through which the database
+ server should be accessed.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_DB_NAME</term>
+ <listitem>
+ <para>
+ Type: string</para>
+ <para>
+ Default: planetlab3</para>
+ <para>The name of the database to access.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_DB_USER</term>
+ <listitem>
+ <para>
+ Type: string</para>
+ <para>
+ Default: pgsqluser</para>
+ <para>The username to use when accessing the
+ database.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_DB_PASSWORD</term>
+ <listitem>
+ <para>
+ Type: password</para>
+ <para>
+ Default: </para>
+ <para>The password to use when accessing the
+ database. If left blank, one will be
+ generated.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_API_ENABLED</term>
+ <listitem>
+ <para>
+ Type: boolean</para>
+ <para>
+ Default: true</para>
+ <para>Enable the API server on this
+ machine.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_API_DEBUG</term>
+ <listitem>
+ <para>
+ Type: boolean</para>
+ <para>
+ Default: false</para>
+ <para>Enable verbose API debugging. Do not enable on
+ a production system!</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_API_HOST</term>
+ <listitem>
+ <para>
+ Type: hostname</para>
+ <para>
+ Default: localhost</para>
+ <para>The fully qualified hostname or IP address of
+ the API server. This hostname must be resolvable and
+ reachable by the rest of your installation, as well as your
+ nodes.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_API_PORT</term>
+ <listitem>
+ <para>
+ Type: int</para>
+ <para>
+ Default: 80</para>
+ <para>The TCP port number through which the API
+ should be accessed. Warning: SSL (port 443) access is not
+ fully supported by the website code yet. We recommend that
+ port 80 be used for now and that the API server either run
+ on the same machine as the web server, or that they both be
+ on a secure wired network.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_API_PATH</term>
+ <listitem>
+ <para>
+ Type: string</para>
+ <para>
+ Default: /PLCAPI/</para>
+ <para>The base path of the API URL.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_API_MAINTENANCE_USER</term>
+ <listitem>
+ <para>
+ Type: string</para>
+ <para>
+ Default: maint@localhost.localdomain</para>
+ <para>The username of the maintenance account. This
+ account is used by local scripts that perform automated
+ tasks, and cannot be used for normal logins.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_API_MAINTENANCE_PASSWORD</term>
+ <listitem>
+ <para>
+ Type: password</para>
+ <para>
+ Default: </para>
+ <para>The password of the maintenance account. If
+ left blank, one will be generated. We recommend that the
+ password be changed periodically.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_API_MAINTENANCE_SOURCES</term>
+ <listitem>
+ <para>
+ Type: hostname</para>
+ <para>
+ Default: </para>
+ <para>A space-separated list of IP addresses allowed
+ to access the API through the maintenance account. The value
+ of this variable is set automatically to allow only the API,
+ web, and boot servers, and should not be
+ changed.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_API_SSL_CRT</term>
+ <listitem>
+ <para>
+ Type: file</para>
+ <para>
+ Default: /etc/planetlab/api_ssl.crt</para>
+ <para>The signed SSL certificate to use for HTTPS
+ access. If not specified or non-existent, a self-signed
+ certificate will be generated.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_API_SSL_KEY</term>
+ <listitem>
+ <para>
+ Type: file</para>
+ <para>
+ Default: /etc/planetlab/api_ssl.key</para>
+ <para>The corresponding SSL private key used for
+ signing the certificate, and for signing slice tickets. If
+ not specified or non-existent, one will be
+ generated.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_API_SSL_KEY_PUB</term>
+ <listitem>
+ <para>
+ Type: file</para>
+ <para>
+ Default: /etc/planetlab/api_ssl.pub</para>
+ <para>The corresponding SSL public key. If not
+ specified or non-existent, one will be
+ generated.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_WWW_ENABLED</term>
+ <listitem>
+ <para>
+ Type: boolean</para>
+ <para>
+ Default: true</para>
+ <para>Enable the web server on this
+ machine.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_WWW_DEBUG</term>
+ <listitem>
+ <para>
+ Type: boolean</para>
+ <para>
+ Default: false</para>
+ <para>Enable debugging output on web pages. Do not
+ enable on a production system!</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_WWW_HOST</term>
+ <listitem>
+ <para>
+ Type: hostname</para>
+ <para>
+ Default: localhost</para>
+ <para>The fully qualified hostname or IP address of
+ the web server. This hostname must be resolvable and
+ reachable by the rest of your installation, as well as your
+ nodes.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_WWW_PORT</term>
+ <listitem>
+ <para>
+ Type: int</para>
+ <para>
+ Default: 80</para>
+ <para>The TCP port number through which the
+ unprotected portions of the web site should be
+ accessed.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_WWW_SSL_PORT</term>
+ <listitem>
+ <para>
+ Type: int</para>
+ <para>
+ Default: 443</para>
+ <para>The TCP port number through which the protected
+ portions of the web site should be accessed.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_WWW_SSL_CRT</term>
+ <listitem>
+ <para>
+ Type: file</para>
+ <para>
+ Default: /etc/planetlab/www_ssl.crt</para>
+ <para>The signed SSL certificate to use for HTTPS
+ access. If not specified or non-existent, a self-signed
+ certificate will be generated.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_WWW_SSL_KEY</term>
+ <listitem>
+ <para>
+ Type: file</para>
+ <para>
+ Default: /etc/planetlab/www_ssl.key</para>
+ <para>The corresponding SSL private key. If not
+ specified or non-existent, one will be
+ generated.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_BOOT_ENABLED</term>
+ <listitem>
+ <para>
+ Type: boolean</para>
+ <para>
+ Default: true</para>
+ <para>Enable the boot server on this
+ machine.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_BOOT_HOST</term>
+ <listitem>
+ <para>
+ Type: hostname</para>
+ <para>
+ Default: localhost</para>
+ <para>The fully qualified hostname or IP address of
+ the boot server. This hostname must be resolvable and
+ reachable by the rest of your installation, as well as your
+ nodes.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_BOOT_PORT</term>
+ <listitem>
+ <para>
+ Type: int</para>
+ <para>
+ Default: 80</para>
+ <para>The TCP port number through which the
+ unprotected portions of the boot server should be
+ accessed.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_BOOT_SSL_PORT</term>
+ <listitem>
+ <para>
+ Type: int</para>
+ <para>
+ Default: 443</para>
+ <para>The TCP port number through which the protected
+ portions of the boot server should be
+ accessed.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_BOOT_SSL_CRT</term>
+ <listitem>
+ <para>
+ Type: binary</para>
+ <para>
+ Default: /etc/planetlab/boot_ssl.crt</para>
+ <para>The signed SSL certificate to use for HTTPS
+ access. If not specified, or non-existent a self-signed
+ certificate will be generated.</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>PLC_BOOT_SSL_KEY</term>
+ <listitem>
+ <para>
+ Type: binary</para>
+ <para>
+ Default: /etc/planetlab/boot_ssl.key</para>
+ <para>The corresponding SSL private key. If not
+ specified or non-existent, one will be
+ generated.</para>
+ </listitem>
+ </varlistentry>
+</variablelist>
diff --git a/doc/variables.xsl b/doc/variables.xsl
new file mode 100644
index 0000000..1b3c2e8
--- /dev/null
+++ b/doc/variables.xsl
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+
+<!--
+PLC configuration file-to-DocBook conversion stylesheet
+
+Mark Huang <mlhuang@cs.princeton.edu>
+Copyright (C) 2006 The Trustees of Princeton University
+
+$Id: GenDoc.xsl,v 1.8 2005/10/10 17:46:36 mlhuang Exp $
+-->
+
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version='1.0'>
+
+<xsl:output omit-xml-declaration="yes" encoding="UTF-8" indent="yes" />
+
+<xsl:template match="/">
+
+ <variablelist>
+ <xsl:for-each select="configuration/variables/category">
+ <xsl:variable name="category_id" select="translate(@id,
+ 'abcdefghijklmnopqrstuvwxyz',
+ 'ABCDEFGHIJKLMNOPQRSTUVWXYZ')" />
+ <xsl:for-each select="variablelist/variable">
+ <xsl:variable name="variable_id" select="translate(@id,
+ 'abcdefghijklmnopqrstuvwxyz',
+ 'ABCDEFGHIJKLMNOPQRSTUVWXYZ')" />
+ <varlistentry>
+ <term>
+ <xsl:value-of select="$category_id" />_<xsl:value-of select="$variable_id" />
+ </term>
+ <listitem>
+ <para>
+ Type: <xsl:value-of select="@type" />
+ </para>
+ <para>
+ Default: <xsl:value-of select="value" />
+ </para>
+ <para>
+ <xsl:value-of select="description" />
+ </para>
+ </listitem>
+ </varlistentry>
+ </xsl:for-each>
+ </xsl:for-each>
+
+ </variablelist>
+
+</xsl:template>
+
+</xsl:stylesheet>