X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=doc%2Fmyplc.xml;h=4522b6be446b727aa21733ad3f61e499d5210f09;hb=12d99e092de9c51ffddb5d04372c339fb79dbc21;hp=f5bc22f1a6cf3d718888684074c313f280e1d0cb;hpb=9ffca9a0a663ca70335bcba5756f2561c213a49b;p=myplc.git
diff --git a/doc/myplc.xml b/doc/myplc.xml
index f5bc22f..4522b6b 100644
--- a/doc/myplc.xml
+++ b/doc/myplc.xml
@@ -38,6 +38,15 @@
MLH
Add development environment.
+
+ 1.2
+ August 18, 2006
+ TPT
+
+ Review section on configuration and introduce plc-config-tty.
+ Present implementation details last.
+
+
@@ -107,7 +116,7 @@
some known limitations to this, so here are a couple notes as a
recommended reading before you proceed with the installation.
- As of 9 August 2006 (i.e myplc-0.5) :
+ As of 17 August 2006 (i.e myplc-0.5-2) :
The software is vastly based on Fedora
@@ -201,21 +210,91 @@
-
+
Changing the configuration
After verifying that MyPLC is working correctly, shut it
down and begin changing some of the default variable
values. Shut down MyPLC with service plc stop
- (see ). With a text
- editor, open the file
- /etc/planetlab/plc_config.xml. This file is
- a self-documenting configuration file written in XML. Variables
- are divided into categories. Variable identifiers must be
- alphanumeric, plus underscore. A variable is referred to
- canonically as the uppercase concatenation of its category
- identifier, an underscore, and its variable identifier. Thus, a
- variable with an id of
+ (see ).
+
+ The preferred option for changing the configuration is to
+ use the plc-config-tty tool. This tool comes
+ with the root image, so you need to have it mounted first. The
+ full set of applicable variables is described in , but using the u
+ guides you to the most useful ones. Note that if you
+ plan on federating with other PLCs, it is strongly
+ recommended that you change the PLC_NAME
+ and PLC_SLICE_PREFIX
+ settings.
+ Here is sample session:
+
+
+ Using plc-config-tty for configuration:
+ # plc-config-tty
+Config file /etc/planetlab/configs/site.xml located under a non-existing directory
+Want to create /etc/planetlab/configs [y]/n ? y
+Created directory /etc/planetlab/configs
+Enter command (u for usual changes, w to save, ? for help) u
+== PLC_NAME : [PlanetLab Test] OneLab
+== PLC_SLICE_PREFIX : [pl] thone
+== PLC_ROOT_USER : [root@localhost.localdomain] root@onelab-plc.inria.fr
+== PLC_ROOT_PASSWORD : [root] plain-passwd
+== PLC_MAIL_ENABLED : [false] true
+== PLC_MAIL_SUPPORT_ADDRESS : [root+support@localhost.localdomain] support@one-lab.org
+== PLC_BOOT_HOST : [localhost.localdomain] onelab-plc.inria.fr
+== PLC_NET_DNS1 : [127.0.0.1] 138.96.250.248
+== PLC_NET_DNS2 : [None] 138.96.250.249
+Enter command (u for usual changes, w to save, ? for help) w
+Wrote /etc/planetlab/configs/site.xml
+Merged
+ /etc/planetlab/default_config.xml
+and /etc/planetlab/configs/site.xml
+into /etc/planetlab/plc_config.xml
+You might want to type 'r' (restart plc) or 'q' (quit)
+Enter command (u for usual changes, w to save, ? for help) r
+==================== Stopping plc
+...
+==================== Starting plc
+...
+Enter command (u for usual changes, w to save, ? for help) q
+ # exit
+#
+]]>
+
+
+ If you used this method for configuring, you can skip to
+ the . As an alternative to using
+ plc-config-tty, you may also use a text
+ editor, but this requires some understanding on how the
+ configuration files are used within myplc. The
+ default configuration is stored in a file
+ named /etc/planetlab/default_config.xml,
+ that is designed to remain intact. You may store your local
+ changes in any file located in the configs/
+ sub-directory, that are loaded on top of the defaults. Finally
+ the file /etc/planetlab/plc_config.xml is
+ loaded, and the resulting configuration is stored in the latter
+ file, that is used as a reference.
+
+ Using a separate file for storing local changes only, as
+ plc-config-tty does, is not a workable option
+ with a text editor because it would involve tedious xml
+ re-assembling. So your local changes should go in
+ /etc/planetlab/plc_config.xml. Be warned
+ however that any change you might do this way could be lost if
+ you use plc-config-tty later on.
+
+ This file is a self-documenting configuration file written
+ in XML. Variables are divided into categories. Variable
+ identifiers must be alphanumeric, plus underscore. A variable is
+ referred to canonically as the uppercase concatenation of its
+ category identifier, an underscore, and its variable
+ identifier. Thus, a variable with an id of
slice_prefix in the plc
category is referred to canonically as
PLC_SLICE_PREFIX.
@@ -249,13 +328,29 @@
system.
- The full set of applicable variables is described in . After changing these variables,
+ After changing these variables,
save the file, then restart MyPLC with service plc
start. You should notice that the password of the
default administrator account is no longer
root, and that the default site name includes
- the name of your PLC installation instead of PlanetLab.
+ the name of your PLC installation instead of PlanetLab. As a
+ side effect of these changes, the ISO images for the boot CDs
+ now have new names, so that you can freely remove the ones names
+ after 'PlanetLab Test', which is the default value of
+ PLC_NAME
+
+
+ Login as a real user
+
+ Now that myplc is up and running, you can connect to the
+ web site that by default runs on port 80. You can either
+ directly use the default administrator user that you configured
+ in PLC_ROOT_USER and
+ PLC_ROOT_PASSWORD, or create a real user through
+ the 'Joining' tab. Do not forget to select both PI and tech
+ roles, and to select the only site created at this stage.
+ Login as the administrator to enable this user, then login as
+ the real user.
@@ -422,12 +517,13 @@ PLC: Signing node packages: [ OK ]
If this step fails, it is likely that the previous step
(Starting web server) also failed. Another
reason that it could fail is if PLC_API_HOST (see
- ) does not resolve to
+ ) does not resolve to
the host on which the API server has been enabled. By default,
all services, including the API server, are enabled and run on
the same host, so check that PLC_API_HOST is
either localhost or resolves to a local IP
- address.
+ address. Also check that PLC_ROOT_USER looks like
+ an e-mail address.
Starting crond: If this step
fails, it is likely that the previous steps (Starting
@@ -528,6 +624,15 @@ PLC: Signing node packages: [ OK ]
Service uses to determine the state of slices. These XML
files are refreshed periodically by cron
jobs running in the MyPLC root.
+
+ /root: this is the
+ location of the root-user's homedir, and for your
+ convenience is stored under /data so
+ that your local customizations survive across
+ updates - this feature is inherited from the
+ myplc-devel package, where it is probably
+ more useful.
+
@@ -598,6 +703,20 @@ PLC: Signing node packages: [ OK ]
+
+ Configuration
+
+ The default configuration should work as-is on most
+ sites. Configuring the development package can be achieved in a
+ similar way as for myplc, as described in
+ . plc-config-tty supports a
+ -d option for supporting the
+ myplc-devel case, that can be useful in a
+ context where it would not guess it by itself. Refer to for a list of variables.
+
+
Files and directories
involved in <emphasis>myplc-devl</emphasis>
@@ -651,8 +770,12 @@ PLC: Signing node packages: [ OK ]
directory are themselves source controlled; see for more information about executing
builds.
-
-
+
+ /root: this is the
+ location of the root-user's homedir, and for your
+ convenience is stored under /data so
+ that your local customizations survive across
+ updates.
/etc/init.d/plc-devel: This file is
@@ -795,12 +918,14 @@ make -C $DATE]]>
Because the CVS repository is not automatically upgraded,
if you wish to keep your local repository synchronized with the
public PlanetLab repository, it is highly recommended that you
- use CVS's support for vendor
- branches to track changes. Vendor branches ease the task
- of merging upstream changes with your local modifications. To
- import a new snapshot into your local repository (for example,
- if you have just upgraded from
+ use CVS's support for vendor branches to track changes, as
+ described here
+ and here.
+ Vendor branches ease the task of merging upstream changes with
+ your local modifications. To import a new snapshot into your
+ local repository (for example, if you have just upgraded from
myplc-devel-0.4-2 to
myplc-devel-0.4-3 and you notice the new
repository in /plc/devel/data/cvs-0.4-3),
@@ -828,17 +953,22 @@ cvs -d /cvs rtag before-myplc-0_4-3-merge
TMP=$(mktemp -d /data/export.XXXXXX)
pushd $TMP
cvs -d /data/cvs-0.4-3 export -r HEAD .
-cvs -d /cvs import -m "PlanetLab sources from myplc-0.4-3" -ko -I ! . planetlab myplc-0_4-3
+cvs -d /cvs import -m "Merging myplc-0.4-3" -ko -I ! . planetlab myplc-0_4-3
popd
rm -rf $TMP]]>
- If there any merge conflicts, use the command suggested by
- CVS to help the merge. Explaining how to fix merge conflicts is
- beyond the scope of this document; consult the CVS documentation
- for more information on how to use CVS.
-
-
+ If there are any merge conflicts, use the command
+ suggested by CVS to help the merge. Explaining how to fix merge
+ conflicts is beyond the scope of this document; consult the CVS
+ documentation for more information on how to use CVS.
+
+
+ More information : the FAQ wiki page
+
+ Please refer to, and feel free to contribute,
+the FAQ page on the Princeton's wiki .
Configuration variables (for <emphasis>myplc</emphasis>)
@@ -850,7 +980,22 @@ rm -rf $TMP]]>
templates that should be placed in
/etc/planetlab/configs/.
- &Variables;
+ This information is available online within
+ plc-config-tty, e.g.:
+
+Advanced usage of plc-config-tty
+ # plc-config-tty
+Enter command (u for usual changes, w to save, ? for help) V plc_dns
+========== Category = PLC_DNS
+### Enable DNS
+# Enable the internal DNS server. The server does not provide reverse
+# resolution and is not a production quality or scalable DNS solution.
+# Use the internal DNS server only for small deployments or for testing.
+PLC_DNS_ENABLED
+]]>
+
+ List of the myplc configuration variables:
+ &Variables;