From: Thierry Parmentelat Date: Fri, 18 Aug 2006 09:53:25 +0000 (+0000) Subject: plc-config-tty as the preferred config method - regenerate X-Git-Tag: planetlab-4_0-rc1~101 X-Git-Url: http://git.onelab.eu/?a=commitdiff_plain;h=717cfbe7cb8ceb3a6175223e140137a77ee96ffe;p=myplc.git plc-config-tty as the preferred config method - regenerate --- diff --git a/doc/myplc.pdf b/doc/myplc.pdf index 05df6a7..8e21f87 100644 Binary files a/doc/myplc.pdf and b/doc/myplc.pdf differ diff --git a/doc/myplc.php b/doc/myplc.php index b9f7614..60b4917 100644 --- a/doc/myplc.php +++ b/doc/myplc.php @@ -13,7 +13,7 @@

-MyPLC User's Guide

+MyPLC User's Guide

Mark Huang

@@ -45,39 +45,41 @@

Table of Contents

-
1. Overview
-
1.1. Purpose of the myplc-devel +
1. Overview
+
1.1. Purpose of the myplc-devel package
2. Requirements
3. Installating and using MyPLC
-
3.1. Installing MyPLC.
+
3.1. Installing MyPLC.
3.2. QuickStart
-
3.3. Changing the configuration
-
3.4. Installing nodes
-
3.5. Administering nodes
-
3.6. Creating a slice
-
3.7. Understanding the startup sequence
-
3.8. Files and directories +
3.3. Changing the configuration
+
3.4. Login as a real user
+
3.5. Installing nodes
+
3.6. Administering nodes
+
3.7. Creating a slice
+
3.8. Understanding the startup sequence
+
3.9. Files and directories involved in myplc
4. Rebuilding and customizing MyPLC
-
4.1. Installation
-
4.2. Files and directories +
4.1. Installation
+
4.2. Configuration
+
4.3. Files and directories involved in myplc-devl
-
4.3. Fedora Core 4 mirror requirement
-
4.4. Building MyPLC
-
4.5. Updating CVS
+
4.4. Fedora Core 4 mirror requirement
+
4.5. Building MyPLC
+
4.6. Updating CVS
A. Configuration variables (for myplc)
B. Development configuration variables (for myplc-devel)
-
Bibliography
+
Bibliography

-1. Overview

+1. Overview

MyPLC is a complete PlanetLab Central (PLC) portable installation contained within a chroot jail. The default installation consists of a web server, an @@ -100,7 +102,7 @@

-1.1.  Purpose of the myplc-devel +1.1.  Purpose of the myplc-devel package

The myplc package comes with all required node software, rebuilt from the public PlanetLab CVS @@ -127,7 +129,7 @@

However, things are never that simple and there indeed are 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 Core 4. Please note that the build server at Princeton @@ -167,7 +169,7 @@ practically any Linux 2.6 based distribution.

    -3.1. Installing MyPLC.

    +3.1. Installing MyPLC.

  • If your distribution supports RPM:

    @@ -181,8 +183,8 @@ # rpm2cpio /tmp/myplc-0.4-1.planetlab.i386.rpm | cpio -diu
-

The Section 3.8, “ Files and directories +

The Section 3.9, “ Files and directories involved in myplc” below explains in details the installation strategy and the miscellaneous files and directories involved.

@@ -194,14 +196,14 @@ the service command to invoke System V init scripts. As the examples suggest, the service must be started as root:

-

Example 1. Starting MyPLC:

+

Example 1. Starting MyPLC:

# service plc start
-

Example 2. Stopping MyPLC:

+

Example 2. Stopping MyPLC:

# service plc stop
-

In Section 3.7, “Understanding the startup sequence”, we provide greater +

In Section 3.8, “Understanding the startup sequence”, we provide greater details that might be helpful in the case where the service does not seem to take off correctly.

Like all other registered System V init services, MyPLC is @@ -210,29 +212,90 @@ chkconfig command on a Red Hat or Fedora host system:

-

Example 3. Disabling automatic startup of MyPLC.

+

Example 3. Disabling automatic startup of MyPLC.

# chkconfig plc off
-

Example 4. Re-enabling automatic startup of MyPLC.

+

Example 4. Re-enabling automatic startup of MyPLC.

# chkconfig plc on

-3.3. Changing the configuration

+3.3. 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 Section 3.2, “ QuickStart ”). 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 Section 3.2, “ QuickStart ”).

+

The preferred option for changing the configuration is to + use the plc-config-tty tool. This tools comes + with the root image, so you need to have it mounted first. The + full set of applicable variables is described in Appendix B, Development configuration variables (for myplc-devel), but using the u + guides you to the most useful ones. Here is sample session: +

+
+

Example 5. Using plc-config-tty for configuration:

+
# service plc mount
+Mounting PLC:                                              [  OK  ]
+# chroot /plc/root su - 
+<plc> # 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_ROOT_USER : [root@localhost.localdomain] odie.inria.fr
+== PLC_ROOT_PASSWORD : [root] plain-passwd
+== PLC_MAIL_SUPPORT_ADDRESS : [root+support@localhost.localdomain] support@one-lab.org
+== PLC_DB_HOST : [localhost.localdomain] odie.inria.fr
+== PLC_API_HOST : [localhost.localdomain] odie.inria.fr
+== PLC_WWW_HOST : [localhost.localdomain] odie.inria.fr
+== PLC_BOOT_HOST : [localhost.localdomain] odie.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
+<plc> # exit
+# 
+
+
+

If you used this method for configuring, you can skip to + the next section. 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.

@@ -260,16 +323,33 @@ preferred FQDN and external IP address of your host system.

-

The full set of applicable variables is described in Appendix B, Development configuration variables (for myplc-devel). 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

+ +
+

+3.4.  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.

-3.4. Installing nodes

+3.5. Installing nodes

Install your first node by clicking Add Node under the Nodes tab. Fill in all the appropriate details, then click @@ -293,12 +373,12 @@

-3.5. Administering nodes

+3.6. Administering nodes

You may administer nodes as root by using the SSH key stored in /etc/planetlab/root_ssh_key.rsa.

-

Example 5. Accessing nodes via SSH. Replace +

Example 6. Accessing nodes via SSH. Replace node with the hostname of the node.

ssh -i /etc/planetlab/root_ssh_key.rsa root@node
@@ -321,7 +401,7 @@

-3.6. Creating a slice

+3.7. Creating a slice

Create a slice by clicking Create Slice under the Slices tab. Fill in all the appropriate details, then click Create. Add @@ -336,7 +416,7 @@ to determine if it needs to create or delete any slices. You may accelerate this process manually if desired.

-

Example 6. Forcing slice creation on a node.

+

Example 7. Forcing slice creation on a node.

# Update slices.xml immediately
 service plc start crond
 
@@ -347,12 +427,12 @@ vserver pl_conf exec service pl_conf restart

-3.7. Understanding the startup sequence

+3.8. Understanding the startup sequence

During service startup described in Section 3.2, “ QuickStart ”, observe the output of this command for any failures. If no failures occur, you should see output similar to the following:

-

Example 7. A successful MyPLC startup.

+

Example 8. A successful MyPLC startup.

Mounting PLC:                                              [  OK  ]
 PLC: Generating network files:                             [  OK  ]
 PLC: Starting system logger:                               [  OK  ]
@@ -405,7 +485,7 @@ 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
-      Section 3.3, “Changing the configuration”) does not resolve to
+      Section 3.3, “Changing the configuration”) 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
@@ -431,7 +511,7 @@ PLC: Signing node packages:                                [  OK  ]

-3.8.  Files and directories +3.9.  Files and directories involved in myplc

MyPLC installs the following files and directories:

    @@ -540,7 +620,7 @@ PLC: Signing node packages: [ OK ] repository.

    -4.1. Installation

    +4.1. Installation

Install the MyPLC development environment similarly to how you would install MyPLC. You may install both packages on the same host system if you wish. As with MyPLC, the MyPLC development @@ -564,7 +644,18 @@ PLC: Signing node packages: [ OK ]

-4.2.  Files and directories +4.2. 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 + Section 3.3, “Changing the configuration”. 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 Appendix B, Development configuration variables (for myplc-devel) for a list of variables.

+
+
+

+4.3.  Files and directories involved in myplc-devl

The MyPLC development environment installs the following files and directories:

@@ -599,14 +690,14 @@ PLC: Signing node packages: [ OK ] snapshot of the PlanetLab source code is stored as a CVS repository in this directory. Files in this directory will not be updated by an upgrade of - myplc-devel. See Section 4.5, “Updating CVS” for more information about updating + myplc-devel. See Section 4.6, “Updating CVS” for more information about updating PlanetLab source code.

  • /build: Builds are stored in this directory. This directory is bind mounted onto /plc/devel/root/build so that it is accessible as /build from within the chroot jail. The build scripts in this - directory are themselves source controlled; see Section 4.4, “Building MyPLC” for more information about executing + directory are themselves source controlled; see Section 4.5, “Building MyPLC” for more information about executing builds.

    • @@ -618,7 +709,7 @@ PLC: Signing node packages: [ OK ]

    -4.3. Fedora Core 4 mirror requirement

    +4.4. Fedora Core 4 mirror requirement

    The MyPLC development environment requires access to a complete Fedora Core 4 i386 RPM repository, because several different filesystems based upon Fedora Core 4 are constructed @@ -650,7 +741,7 @@ PLC: Signing node packages: [ OK ] such as wget or rsync to download the RPMS from a public mirror:

    -

    Example 8. Setting up a local Fedora Core 4 repository.

    +

    Example 9. Setting up a local Fedora Core 4 repository.

    # mkdir -p /plc/devel/data/fedora
 # cd /plc/devel/data/fedora
 
@@ -668,7 +759,7 @@ PLC: Signing node packages:                                [  OK  ]

    -4.4. Building MyPLC

    +4.5. Building MyPLC

    All PlanetLab source code modules are built and installed as RPMS. A set of build scripts, checked into the build/ directory of the PlanetLab CVS @@ -686,7 +777,7 @@ PLC: Signing node packages: [ OK ] within the MyPLC development environment, execute the following commands as root:

    -

    Example 9. Building MyPLC.

    +

    Example 10. Building MyPLC.

    # Initialize MyPLC development environment
 service plc-devel start
 
@@ -713,7 +804,7 @@ make -C $DATE

    -4.5. Updating CVS

    +4.6. Updating CVS

    A complete snapshot of the PlanetLab source code is included with the MyPLC development environment as a CVS repository in /plc/devel/data/cvs. This CVS repository may @@ -741,7 +832,7 @@ make -C $DATE execute the following commands as root from within the MyPLC development environment:

    -

    Example 10. Updating /data/cvs from /data/cvs-0.4-3.

    +

    Example 11. Updating /data/cvs from /data/cvs-0.4-3.

    Warning: This may cause severe, irreversible changes to be made to your local repository. Always tag your local repository before @@ -778,6 +869,21 @@ rm -rf $TMP variables and their defaults may be defined in site-specific XML templates that should be placed in /etc/planetlab/configs/.

    +

    This information is available online within + plc-config-tty, e.g.:

    +
    +

    Example A.1. Advanced usage of plc-config-tty

    +
    <plc> # 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:

    PLC_NAME
    @@ -1397,7 +1503,7 @@ rm -rf $TMP

    Type: string

    - Default: file:///usr/share/mirrors/fedora

    + Default: file:///data/fedora

    Fedora Core mirror from which to install filesystems.

    @@ -1422,7 +1528,7 @@ rm -rf $TMP

    -Bibliography

    +Bibliography

    [1] Mark Huang. PlanetLab Technical Contact's Guide.

    diff --git a/doc/myplc.xml b/doc/myplc.xml index f5bc22f..5abeb58 100644 --- a/doc/myplc.xml +++ b/doc/myplc.xml @@ -107,7 +107,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 +201,87 @@ -
    +
    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 tools 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. 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_ROOT_USER : [root@localhost.localdomain] odie.inria.fr +== PLC_ROOT_PASSWORD : [root] plain-passwd +== PLC_MAIL_SUPPORT_ADDRESS : [root+support@localhost.localdomain] support@one-lab.org +== PLC_DB_HOST : [localhost.localdomain] odie.inria.fr +== PLC_API_HOST : [localhost.localdomain] odie.inria.fr +== PLC_WWW_HOST : [localhost.localdomain] odie.inria.fr +== PLC_BOOT_HOST : [localhost.localdomain] odie.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 next section. 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 +315,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,7 +504,7 @@ 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 @@ -598,6 +680,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> @@ -850,7 +946,23 @@ 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;
    Revision History