Baracus Users Guide 1.1

Document Sample
Baracus Users Guide 1.1 Powered By Docstoc
					                            http://baracus-project.org




Baracus Users Guide 1.1

Daniel Westervelt, Novell
David Bahi, Novell
Robert Bell, Novell
Sven Dietrich, Novell




                                                    1
                                                                                                                                  http://baracus-project.org
Table of Contents
1 Executive Summary............................................................................................................................................ 5
    1.1 Overview..................................................................................................................................................... 5
    1.2 What makes Baracus so different............................................................................................................... 5
2 Installation and Setup......................................................................................................................................... 6
    2.1 Support Specifications................................................................................................................................ 6
    2.2 Installation sources..................................................................................................................................... 7
    2.3 Packages.................................................................................................................................................... 7
    2.4 Default system settings............................................................................................................................... 8
    2.5 Starting Services......................................................................................................................................... 9
       2.5.1 Required services............................................................................................................................... 9
       2.5.2 Syslog-ng required.............................................................................................................................. 9
       2.5.3 Provided services............................................................................................................................... 9
       2.5.4 Check services log files ................................................................................................................... 10
    2.6 Firewall modifications............................................................................................................................... 10
3 Prerequisites..................................................................................................................................................... 11
    3.1 Network boot, DHCP, and remote power.................................................................................................. 11
    3.2 Network boot in BIOS boot order.............................................................................................................. 11
    3.3 TFTP file name and next-server IP address..............................................................................................11
4 Booting Basics.................................................................................................................................................. 12
    4.1 Bootstrapping............................................................................................................................................ 12
    4.2 Registration and Inventory........................................................................................................................ 12
    4.3 IPMI Auto-Configuration............................................................................................................................ 12
5 Remote Power Controller.................................................................................................................................. 13
    5.1 bapower help............................................................................................................................................ 13
    5.2 Define node power management.............................................................................................................. 13
    5.3 List power managed nodes....................................................................................................................... 14
    5.4 Remove node power management entry.................................................................................................. 14
    5.5 Query power status of node...................................................................................................................... 14
    5.6 Remote control of node power.................................................................................................................. 14
6 Storage Devices............................................................................................................................................... 15
    6.1 Adding storage targets.............................................................................................................................. 15
       6.1.1 Adding iSCSI storage targets............................................................................................................ 15
       6.1.2 Adding NFS storage targets.............................................................................................................. 16
    6.2 Listing storage targets.............................................................................................................................. 16
    6.3 Displaying details on storage targets........................................................................................................ 16
    6.4 Removing storage targets......................................................................................................................... 16
7 Node Boot Directives........................................................................................................................................ 17
    7.1 bado help.................................................................................................................................................. 17
    7.2 Empty....................................................................................................................................................... 17
    7.3 Inventory................................................................................................................................................... 17
    7.4 Pxewait..................................................................................................................................................... 17
    7.5 Localboot.................................................................................................................................................. 18
    7.6 Net boot.................................................................................................................................................... 18
       7.6.1 iSCSI Net boot.................................................................................................................................. 18
       7.6.2 NFS Net boot.................................................................................................................................... 18
       7.6.3 Netboot storage registration.............................................................................................................. 19
    7.7 Rescue...................................................................................................................................................... 19
    7.8 Wipe......................................................................................................................................................... 19
    7.9 Image (unicast)......................................................................................................................................... 20
    7.10 Image (multicast).................................................................................................................................... 20
    7.11 Clone....................................................................................................................................................... 20




                                                                                                                                                                      2
                                                                                                                                  http://baracus-project.org
   7.12 Build........................................................................................................................................................ 21
       7.12.1 Build and remote access................................................................................................................. 22
       7.12.2 Build and remote logging................................................................................................................ 22
       7.12.3 Build and Network-hosted storage.................................................................................................. 23
8 XEN Support..................................................................................................................................................... 24
   8.1 Xen PXE boot Support.............................................................................................................................. 24
   8.2 Xen DHCP Configuration.......................................................................................................................... 24
   8.3 Xen VM Configuration............................................................................................................................... 25
9 Multicast Channels........................................................................................................................................... 26
   9.1 Create a multicast channel....................................................................................................................... 26
   9.2 Listing registered channels....................................................................................................................... 26
   9.3 Channel details......................................................................................................................................... 26
   9.4 Removing registered channels................................................................................................................. 26
10 Network Install Sources.................................................................................................................................. 27
   10.1 Basource help......................................................................................................................................... 27
   10.2 Locating distribution ISOs....................................................................................................................... 27
   10.3 Creating a network install source............................................................................................................ 28
       10.3.1 Addons............................................................................................................................................ 28
       10.3.2 DUDs.............................................................................................................................................. 28
   10.4 Listing available install sources............................................................................................................... 29
   10.5 Removal of network install sources........................................................................................................ 29
   10.6 Managing install sources........................................................................................................................ 29
   10.7 Manual override of service status........................................................................................................... 30
11 Configuration Containers................................................................................................................................ 31
   11.1 Configuration overview............................................................................................................................ 31
   11.2 baconfig help........................................................................................................................................... 31
   11.3 Creating a configuration container.......................................................................................................... 32
   11.4 Listing configuration containers............................................................................................................... 32
   11.5 Removing configuration.......................................................................................................................... 32
   11.6 Configuration detail................................................................................................................................. 32
   11.7 Exporting configuration to a file............................................................................................................... 32
   11.8 Updating configuration or adding a new version.....................................................................................33
   11.9 Container types....................................................................................................................................... 33
       11.9.1 Profile Containers........................................................................................................................... 33
       11.9.2 Module Containers.......................................................................................................................... 33
       11.9.3 Hardware Containers...................................................................................................................... 34
       11.9.4 Autobuild Containers....................................................................................................................... 35
       11.9.5 File.................................................................................................................................................. 36
12 Repositories.................................................................................................................................................... 37
   12.1 barepo help............................................................................................................................................. 37
   12.2 Creating a repository.............................................................................................................................. 37
   12.3 Adding packages to a repository............................................................................................................. 37
   12.4 Listing available repositories................................................................................................................... 37
   12.5 Removal of a repository.......................................................................................................................... 38
   12.6 Verification and update of a repository.................................................................................................... 38
13 Managing Node Related Information.............................................................................................................. 39
   13.1 Defining nodes........................................................................................................................................ 39
   13.2 bahost help............................................................................................................................................. 39
   13.3 Pre-staging a node entry......................................................................................................................... 39
   13.4 Listing known node information.............................................................................................................. 39
   13.5 Fancy filtering on queries........................................................................................................................ 40
   13.6 Setting a nodes administrative state....................................................................................................... 40
   13.7 Purging all node information................................................................................................................... 40
   13.8 Displaying node details........................................................................................................................... 40
   13.9 Baracus states for nodes........................................................................................................................ 41


                                                                                                                                                                      3
                                                                                                                          http://baracus-project.org
14 Logs and Audit History.................................................................................................................................... 42
   14.1 Historical state look-up............................................................................................................................ 42
   14.2 Historical command look-up.................................................................................................................... 42
   14.3 Exporting audit data................................................................................................................................ 42
15 Appendix A – Baracus Hooks.......................................................................................................................... 43
16 Appendix B - distros.xml................................................................................................................................. 44
17 Appendix C – Creating WinPE Setup.............................................................................................................. 45




                                                                                                                                                              4
                                                                                         http://baracus-project.org


                                 1 Executive Summary
1.1 Overview

   Baracus is an open source boot and build management tool. Broadly, this includes power management,
   boot management and provisioning management. More specifically, Baracus provides hardware
   inventory, booting, building, cloning, imaging, rescuing, and decommissioning.

   Our mission is to stick to one area of systems management, and to do it better than anyone else. To this
   goal, Baracus is focused on delivering an incredibly feature rich, easy to use, integrated enterprise
   management solution.


1.2 What makes Baracus so different

   For starters, Baracus provides an integrated power management subsystem which allows administrators
   to remotely control the power states of their servers. All major vendors specific Baseboard Management
   Controller (BMC) directives are reduced to simple and consistent control statements. No longer do you
   need to remember BMC address, username, password, syntax, etc... just to control a system. Additionally,
   access and audit is tied back to a roles based model, so you have a complete history of who issued power
   directives and when.

   Second, Baracus introduces the concept of a centralized boot controller. This means that any system
   registered with Baracus can be remotely powered and also remotely directed on how and where to boot.
   This becomes a very powerful concept when you consider that from a remote location you can now
   instruct a system to boot to any of the following boot states; wait, inventory, local boot, network boot, build,
   image, clone, rescue and wipe. As with power management, access and audit is tied back to a roles
   based model so you have a complete history of who booted to what and when.

   Third, Baracus has a highly advanced system provisioning framework that can manage both system builds
   and system images. For system builds, Baracus integrates with native system builders such as: autoyast,
   kickstart, preseed, weasel, auto-unattended, and jumpstart. For each of these build types, Baracus also
   controls all the service and source requirements. Gone are the days of having to manually provide remote
   install sources and configure a host of services just to build a system. As an alternative to system
   provisioning via native builders, Baracus also supports system imaging on both a unicast and multi-cast
   scale. Again, as with all other components, all provisioning access and audit is tied back to a roles based
   model so you have a complete audit trail. Additionally, Baracus can act as a central log manager for all
   build and image logs.

   What makes Baracus so different, is our move from the legacy, cumbersome static pxe/tftp control models,
   to the next generation of technologies, which provide the basis of everything we do.




                                                                                                                  5
                                                                                       http://baracus-project.org


                               2 Installation and Setup
   Baracus is primarily a service that interacts with nodes using a remote BIOS level payload that is
   delivered, most commonly, via a network bootstrap.

   There are two main modes of operation with Baracus. The primary is when Baracus acts as standard boot
   manager for a set of nodes, where every node boot transitions via a network boot cycle on every boot.

   The second mode of operation is when Baracus is used in a one time staging scenario. This mode is
   primarily used for a build lab setup where Baracus can either interact with nodes via selective
   delegation/fallback based on BIOS boot order or via direct administrator intervention during BIOS post.
   Additionally, Baracus boot targeting can be accomplished via a bootable Baracus USB key which can be
   used to load the Baracus payload on demand.

   Baracus directly interacts with nodes only during their boot cycle. Beginning with the initial network boot,
   Baracus controls node transitions through subsequent event chains from discovery, deployment to
   disposal. Once a node is up and running and all necessary boot or build actions are complete, Baracus
   delegates boot control and management of active state to the node and it's operator.

   In a disconnected, non boot manager mode, Baracus can re-acquire boot control over a given node at any
   time, facilitating automation of administration, compliance and evaluation.


2.1 Support Specifications

   The preferred deployment method for Baracus is to install directly to server class hardware, a 64bit CPU
   with at least 4G RAM, and gigabit ethernet. Note also that operating system ISOs require significant
   storage so adequate storage, or a mountable share for these ISOs, will be needed.

   The Baracus build management server is currently certified to run on the following distributions:

   SLES 11 SP1

   openSUSE 11.4

   Baracus is currently built to run on both x86 and x86_64 architectures.

   Baracus can provision and make available many distributions for nodes to build. Currently supported
   distributions are: SLES, openSUSE, RedHat Enterprise Linux, Fedora, CentOS, Ubuntu Server and
   Desktop, Debian, VMware ESX, Windows Server 2008, Windows 7, SLES on z/VM guests on IBM System
   z, Solaris. We are also actively working on BSD and AIX support as well.




                                                                                                                  6
                                                                                    http://baracus-project.org
2.2 Installation sources

   Add the installation sources for Baracus. For openSUSE 11.4:
zypper ar -f \
http://download.opensuse.org/repositories/systemsmanagement:/baracus/openSUSE_1
1.4 baracus


   or for SLES11 SP1:
zypper ar -f \
http://download.opensuse.org/repositories/systemsmanagement:/baracus/SLE_11_SP1
baracus



2.3 Packages

   Baracus rpms are listed below.

           baracus                                           Baracus server and command line
           baracus-kernel                                    Baracus Linux and initrd workloads

   To install the Baracus rpms:
zypper in baracus baracus-kernel

   With proper install sources configured for the Baracus repositories, any other package dependencies will
   be resolved automatically.




                                                                                                              7
                                                                                         http://baracus-project.org
2.4 Default system settings

   System wide Baracus configuration settings can be modified using the following file:

           /etc/sysconfig/baracus

   In order to apply any changes, there are service(s) that must be restarted; these are noted in the header
   section for each configuration option.

 BASE_DIR=~baracus              By default, this is the home directory of the 'baracus' user. Several sub
                                directories are expected to reside at this location so just pointing this to an
                                empty, or nonexistent directory is not advised.


 SERVER_IP=                     IP address of the Baracus server. If left unset, the IP address of the first
                                link-up interface of the host machine will be used.


 SHARE_TYPE=nfs                 The default build service protocol to use for sharing files to be installed.
                                This can be either NFS (default) or HTTP. (This setting can be overridden
                                for any specific source entry with the basource update command using
                                the --sharetype option.)


 SHARE_IP=                      IP address of the file server of the BASE_DIR/builds directory. If left unset,
                                this will use the SERVER_IP value. This should be the IP of the server
                                responsible for running the config SHARE_TYPE protocol. Typically, this
                                would be the same address as the SERVER_IP. (This setting can be
                                overridden with the basource update command using the --shareip
                                option.)


 BARACUSD_OPTIONS=”none” Currently the only valid options are 'none' or 'debug'.


 REMOTE_LOGGING=”no”            If “yes” then remote hosts builds will to log to the Baracus server. Logs are
                                placed in BASE_DIR/logs/remote. The default value for this option is "no".


 IPMI=”true”                    If set to “true” then the initial payload deployed to a system will test for
                                IPMI support and if present, will configure a new IPMI userid named
                                “baracus”. This userid will be created at the first free ipmi user slot. Upon
                                success, this ipmi userid will also be automatically entered into the
                                Baracus power management subsystem allowing for immediate power
                                control of the node via the bapower command.


 IPMI_LAN=”true”                If set to “true” then the initial payload that is deployed will test for IPMI
                                support and if present will configure IPMI networking to DHCP.


 IPMI_PASSWD=”baracus”          This is the password to use when creating the baracus IPMI userid
                                associated with the IPMI sysconfig option.


                                                                                                                  8
                                                                                       http://baracus-project.org
2.5 Starting Services

     After Baracus is installed, we need to make sure the services it requires are running and are configured to
     be started on the next boot. This includes the baracusdb and baracusd services.


2.5.1          Required services

     Baracus has several services that need to be set to run at start-up:
 chkconfig     identd on
 chkconfig     apache2 on
 chkconfig     nfsserver on
 chkconfig     libvirtd on                # if you intend to control Virtual Machines
 chkconfig     smb on                     # if you intend to build Windows OS targets
 chkconfig     nmb on                     # if you intend to build Windows OS targets

 chkconfig tftp off                       # all other tftp servers need to be disabled

     Ensure these services are correctly running:
 service    identd restart
 service    apache2 restart
 service    nfsserver restart
 service    libvirtd restart             # if you intend to build Virtual Machines
 service    smb restart                  # if you intend to build Windows OS targets
 service    nmb restart                  # if you intend to build Windows OS targets

 service tftp stop

2.5.2          Syslog-ng required

     Remote node build logging requires the syslog-ng service. This is not the default with openSUSE 11.4
     and must be configured as follows:

     To enable syslog-ng, edit /etc/sysconfig/syslog to set SYSLOG_DAEMON="syslog-ng" and then
     run:
 service syslog restart

2.5.3          Provided services

     Now configure the Baracus specific services to start on reboot:
 chkconfig baracusdb -- on
 chkconfig baracusd on

     After making sure the SERVER_IP, SHARE_TYPE, and SHARE_IP are configured, start the Baracus
     services:
 service baracusdb restart             # baracusdb must be started before baracusd
 service baracusd restart




                                                                                                               9
                                                                                       http://baracus-project.org
2.5.4        Check services log files

   After starting the services, have a glance at the logs for these services to look for any obvious issues:
 cat ~baracus/logs/initlog            # baracusdb – new with each service start/stop
 cat ~baracus/logs/baracusd           # baracusd – append to over history



2.6 Firewall modifications

   The following protocols/ports must be allowed to pass through the firewall: HTTP (80), HTTPS (443),
   TFTP (69), NFS (2049), CIFS (3020), syslog (514)

   Modification of firewall allowed protocols is outside the scope of Baracus and will require administrator
   intervention to allow the services listed, or disable firewall (not recommended).




                                                                                                               10
                                                                                      http://baracus-project.org


                                       3 Prerequisites
3.1 Network boot, DHCP, and remote power

   In order for Baracus to act as a boot manager, the following is required:

       1. DHCP needs to be configured to serve Baracus payload ( gpxe_baracus.0 or ipxe_baracus.0 )

       2. Each node needs to have its BIOS set to network boot (or enabled with local baracus boot image
          – e.g. usb stick or embedded ROM)

       3.   For the most complete control, nodes need to have their BMC power settings configured.

   Baracus acts as a boot manager and if it has not been programmed with a boot directive for a client node,
   it will not allow that node to boot from it's directly attached storage. Of course, Baracus does not have to
   be a boot manager if the administrator is willing to manage the PXE boot process for a node each time a
   task needs to be performed with Baracus. Additionally, Baracus is does not have to control all systems; it
   can be configured to ignore individual servers or server groups.


3.2 Network boot in BIOS boot order

   Baracus requires a BIOS payload to control the booting of systems thus nodes must either network boot or
   have a local Baracus BIOS payload (e.g. boot able usb stick or embedded ROM). To network boot the
   BIOS, "boot order" must set to the "network boot", "NIC boot " or "PXE boot".


3.3 TFTP file name and next-server IP address

   When network booting, the node will issue a DHCP request for its IP address and then request via TFTP
   the Baracus payload file to fetch and boot. A server (e.g. dhcpd or dnsmasq) must be configured to point
   nodes to the Baracus server IP as "next-server" and provide "gpxe_baracus.0", the filename to be
   retrieved.

   An ISC DHCP configuration file /etc/dhcpd.conf would need the following in its global section:
filename “gpxe_baracus.0”;
next-server <ip>;    # replace <ip> with actual server IP

   A dnsmasq configuration file /etc/dnsmasq would need:
dhcp-boot=gpxe_baracus.0,,<ip>                 # replace <ip> with actual server IP

   Making these adjustments will require administrator intervention.




                                                                                                             11
                                                                                       http://baracus-project.org

                                      4 Booting Basics
4.1 Bootstrapping

   Baracus works by injecting itself before the system bootstraps. When the Baracus payload is loaded, the
   node will communicate with the Baracus server to determine what needs to happen next.

   This can be initiating the registration process as described in Section 4.2 or any of the bado boot
   target/actions.


4.2 Registration and Inventory

   Baracus will register systems once it boots via the Baracus payload, usually via DHCP. The registration
   process is described below:

       1. On the first Baracus enabled boot of a node, Baracus will first discover and register its primary
          MAC address.

       2. Then Baracus will automatically deliver a workload to collect the node's hardware inventory. Also
          at this point, if configured and the node supports it, the workload will discover the IPMI IP address
          and program the IPMI user and password for remote power management.

       3. At the end of the inventory workload, the node will reboot.

       4. On the second network boot of the node, if no predefined boot directive is set, Baracus will direct
          the node to boot to a pxewait console menu and wait indefinitely (it will not roll to boot from locally
          attached storage).

       5. Once a boot directive is set with the bado command, the node can be rebooted either by Baracus
          remote power control, by logging into the pxewait menu console and selecting reboot, or by
          physically power cycling the system.


4.3 IPMI Auto-Configuration
    To fully automate a new node's power management configuration, Baracus can be set to auto-configure
    IPMI and auto-configure power management. This can be accomplished by setting the IPMI values in
    /etc/sysconfig/baracus.
    Once enabled in /etc/sysconfig/baracus, any system new to Baracus will automatically get a 'baracus'
    IPMI userid with the password specified in the IPMI_PASSWD variable. Additionally, if the IPMI_LAN
    variable is set to 'true', the system will automatically have it's IPMI network configured to DHCP.
    Any system not capable of IPMI or with an IPMI baracus userid already configured, will be skipped.
    IPMI auto-configuration removes the burden of having to manually log into a systems BIOS to configure
    remote power management.




                                                                                                               12
                                                                                        http://baracus-project.org

                            5 Remote Power Controller
   Baracus provides the bapower command for remote power management of nodes. This command
   provides a common interface which communicates with a wide variety of power management tools (e.g.,
   IPMI, iLO, DRAC II, DRAC III, RACS, APC, virsh, etc...). This gives you the ability to power on, power off,
   power cycle, and query power status of managed nodes.

   For the most complete automation, Baracus supports auto-configuration of IPMI as described in section
   4.3. This feature removes the burden of having to configure any BIOS settings and/or adding Baracus
   power management entries.


5.1 bapower help

   The bapower help command can take an optional subcommand.
bapower help [<command>]

5.2 Define node power management

   In order to manage the power of a remote system, Baracus must have details about that systems power
   management interface. These details are collected either by the autoIPMI section of the inventory
   workload, or by an administrator, and used to create a Baracus power entry. The entry includes the
   controller address, connection type and any authentication credentials. If collected by the autoIPMI tool, a
   power entry is created by the Baracus system. Otherwise the administrator can use the bapower add
   command:
bapower add --mac <mac> --host <host> \
       --bmcaddr <bmc-ip> --ctype <c-type> --login <login> --pass <password>

   Where:

   <mac> is the MAC address of the managed node, not the MAC of the controller
   <hostname> is the hostname of the managed node, not the name of the controller
   <bmc-ip> is the IP address of the managed node's controller (e.g., BMC IP for IPMI,

              physical host IP for VMs)
   <c-type> is the controller type (e.g., ipmi, ilo, drac, bladecenter, racs, wti, virsh, or vmware)
   <login> is the user identity required to connect to the remote controller, possibly 'none'
   <password> is the password required to connect to the remote controller, possibly 'none'


   The MAC and hostname are strictly used as identifiers of the managed node for other bapower
   commands.




                                                                                                               13
                                                                                  http://baracus-project.org
5.3 List power managed nodes

   To list the currently registered power controller entries, use the bapower list command:
bapower list                [ --mac <mac>       |   --hostname <host> ]

5.4 Remove node power management entry

   To remove an existing power controller entry, use the bapower remove command:
bapower remove              [ --mac <mac>       |   --hostname <host> ]

5.5 Query power status of node

   To query the current power state of a node, use the bapower status command:
bapower status              [ --mac <mac>       |   --hostname <host> ]

5.6 Remote control of node power

   The bapower on/off/cycle commands can be used to control the power of remote systems:
bapower on                  [ --mac <mac>       |   --hostname <host> ]

bapower off                 [ --mac <mac>       |   --hostname <host> ]

bapower cycle               [ --mac <mac>       |   --hostname <host> ]




                                                                                                         14
                                                                                    http://baracus-project.org


                                   6 Storage Devices
   Storage objects are registered with Baracus so they can be assigned as either network boot targets or
   deployable system images. Baracus can only use a storage object if it has been registered and enabled.
   Currently supported storage types are: iscsi, nfs and image. Each type is discussed in later sections to
   which they relate.


6.1 Adding storage targets
 bastorage add --name <name> --type <type> --storage <storage> \
               --size <”size”> --ip <ip> --username <username> \
               --password <password> --description <”description”>

   <name> unique identifier for the storage object

   <type> storage object type (iscsi, nfs, image, clone)

   <ip> ip address of the storage server, not required for type image

   <storage> network or local path to the storage object

   <username> optional username for storage access

   <password> optional password for storage access

   <description> description of the storage

   <size> brief description of the storage size


6.1.1       Adding iSCSI storage targets
 bastorage add --name <name> --type iscsi --storage <storage> --size <”size”> \
               --ip <ip> --username <username> --password <password> \
               --description <”description”>

   <storage>              the target made available by the iSCSI server.
                          Follows syntax iqn.YYYY-MM.{reversed domain name}[:arbitrary naming string]
                          where the owner of the domain name is responsible for everything after the colon
                          in the bracketed arbitrary naming string.

   For example: iqn.2009-12.com.novell:baracus.uniquehostname.disk1




                                                                                                           15
                                                                                    http://baracus-project.org
6.1.2       Adding NFS storage targets
 bastorage add --name <name> --type nfs --storage <storage> --size <”size”> \
               --ip <ip> --username <username> --password <password> \
               --description <”description”>

   <storage>              absolute path of the NFS share on the NFS server.

   For example: /nfsshares/rootfs/root1


6.2 Listing storage targets

   To list all currently registered storage devices, use the bastorage command as follows.
 bastorage list [ --filter name::'*partial*'               | --filter name::specific ]

6.3 Displaying details on storage targets

   To see all known detail information about a storage target, use the bastorage command as follows.
 bastorage detail      --name <name>

6.4 Removing storage targets

   To unregister a specific storage target, use the bastorage command as follows:
 bastorage remove –name <name>

   NOTE: removing/unregistering the storage target does not remove any data from the storage device. It
   simply removes the storage registration from Baracus.




                                                                                                           16
                                                                                         http://baracus-project.org


                                7 Node Boot Directives
   Baracus supports a number of different boot directives that can be assigned to a node. Currently these
   include: inventory, build, image, localboot, netboot, rescue, wipe and empty. All of these boot directives
   are set via the bado command.


7.1 bado help

   The bado help command accepts an optional subcommand. This may be all you need for
   documentation.
bado help [<command>]

7.2 Empty

   When a device has been completely decommissioned, or an entry for it is no longer desired, the bado
   empty command will remove all build and boot relations. Unlike the bahost remove command, this
   does not delete the related inventory, wipe, or image log files from the database.
bado empty { --mac <mac> | --hostname <name> }

7.3 Inventory

   This is the default action of Baracus for all new system registrations. For new systems, Baracus serves an
   inventory workload to a node when the MAC address is discovered making a network boot request.

   NOTE: In fact, the only way to skip the inventory workload is to direct an, as of yet undiscovered node, to
   bado netboot or bado rescue. These pre-staged directives will skip the inventory workload and
   collection.

   If for some reason a refresh of the inventory is desired, one may use the bado inventory command:
bado inventory --mac <mac> [ --hostname <name> ]

   and on the next boot of the host, it will be served the non-destructive inventory collection workload.

   After inventory collection, without any other boot directive, a host will be transitioned to the pxewait state.
   For example, if an earlier bado build command was issued for the node, it will be made ready to build
   following the inventory collection.


7.4 Pxewait

   Any node can be placed in the pxewait state by using the bado pxewait command:
bado pxewait --mac <mac> [ --host <name> ]

   The pxewait state is entered automatically after completion of inventory, unless another action directive
   has already been applied to the node. While a node is in pxewait state, it is accessible via the console and
   via ssh.

                                                                                                                 17
                                                                                          http://baracus-project.org
7.5 Localboot

   If you have a node with the local storage already configured with an operating system, you can boot locally
   by using the bado localboot command:
 bado localboot --mac <mac> [ --host <name> ] \
              [ --drive <dint> --partition <pint> ]

   Where

   <dint> is the zero-based integer of the disk with the bootable partition [default 0]

   <pint> is the zero-based integer of the bootable partition [default 0]

7.6 Net boot

   Baracus can direct nodes to boot from network hosted storage. Currently iSCSI and NFS are supported
   using the bado netboot command:

7.6.1        iSCSI Net boot

   An iSCSI netboot command-line contains the following parameters:
 bado netboot --mac <mac> [--host <name>] --storageid <storageid>

   Where

   <storageid> unique string identifying the target made available by the iSCSI server.

   See the bastorage command for more details on defining storage.

7.6.2        NFS Net boot

   An NFS netboot command-line contains the following parameters:
 bado netboot --mac <mac> [--host <name>] --storageid <storageid>

   Where

   <storageid> is the NFS storage-id associated with an NFS server share as defined by a bado storage
   command.

   Baracus NFS Netboot will mount the NFS share identified by the <storageid> parameter and attempts
   to read the grub menu, Kernel and initrds stored in the NFS file system. If the grub menu or boot files
   cannot be read, Baracus will attempt to boot the node using common default (vmlinuz/initrd) symlinks in
   boot/. The node will enter pxewait if no boot files can be found on the NFS root medium.




                                                                                                                 18
                                                                                       http://baracus-project.org
7.6.3        Netboot storage registration
    In order to be able to boot to network storage, that storage must be registered within Baracus. This can
    be done with the bastorage command as detailed in section 6 of this document.


7.7 Rescue

   Rescue mode can be used to boot a remote rescue image in order to debug issues preventing a localboot.
   The rescue command bado rescue:
 bado rescue --mac <mac> --hostname <name> --ip <addr> --profile <prof> \
   [--hardware <hw>] [--distro <distro>]



7.8 Wipe

   In many cases, decommissioning a system requires data to be securely destroyed to protect critical
   information from being recovered from old hard drives. In order to do this securely, algorithms that make it
   extremely hard to recover data must be used to clean the disk device. Simply removing partitions or
   overwriting data does not protect that data from being recoverable.

   Baracus supports secure system decommissioning via the dban disk wipe utility using the bado wipe
   command:
 bado wipe { --mac <mac> | --hostname <name> } [ --autowipe | --noautowipe ]

   !!WARNING: the wipe subcommand will completely remove all data/partitions from
   your hard drive. Once removed, the data will be unrecoverable – period!!!

   It is important to remember that in order for the bado wipe command to work, the host entry must still be
   registered in Baracus (to prevent an inventory cycle before the wipe).

   By default, the wipe subcommand will run in manual mode. On next boot, this will present the user with a
   menu from which specific hard drives can be selected.

   Baracus also supports an --autowipe option to the bado wipe command.


   !! WARNING: --autowipe will automatically wipe all attached drives including
   iSCSI and other SAN attached LUNS if present !!

    To confirm the --autowipe flag state, you need to use bado list states command:
 bado list states [ --filter <fancy> ] --verbose

   If you have set, or not set, the wipe style to your desired method, simply re-invoke with the desired flag.




                                                                                                                 19
                                                                                         http://baracus-project.org

7.9 Image (unicast)
   To deploy a raw disk image to a node's locally attached storage, you can use the bado image command:
bado image --mac <mac> [ --hostname <name> ] --storageid <storage-id>                                \
           --hardware <hw>

   <storageid> refers to the id of the storage object registered with Baracus. The objects are of type 'image'
   and are created with the bastorage command as described in Section 6. To see available storage
   objects use bastorage list.

   <hw> refers to a baconfig hardware container with a rootdisk value that names the node's drive
   device to be imaged (e.g. /dev/sda, or for a VM with virtio, /dev/vda as found in the hardware-vda
   container provided).

7.10 Image (multicast)

   Then use the bado command to subscribe a node to the channel.
bado image --mac <mac> [ --hostname <name> ] --mcast <name> --hardware <hw>

   These multicast channels (e.g. --mcast <name>) need to be pre-registered with Baracus as described in
   section 9. To see a list of currently available channels use bamcast list.

7.11 Clone
    The clone boot directive can be used to create a golden image of a system. A system set to the clone
    directive will boot into a payload that will prompt the user with a shell. From this shell, one can initiate a
    dd style clone of the specified disk.
    To clone a golden image use the bado command:
bado clone --mac <mac> [ --hostname <name> ] --hardware <hardware> \
           --storageid <storageid>

    Where

    <hardware> refers to a hardware configuration with at minimum a rootdisk defined. This rootdisk will be
    used by the clone payload as the default disk image target. Additionally, any bootargs required for the
    hardware to boot should be defined in this hardware configuration.

    <storageid> refers to the image storage object that the disk clone will be registered and created as. All
    clones images are stored in the ~baracus/images. All clones images are automatically registered. Any
    other images need to be manually registered with the bastorage command as described in Section 6.

    Once the system is booted with the clone directive, connect via a console or ssh and select option 1 to
    clone.

    Alternatively, you can specify –autoclone on the commandline to bypass the manual menu and go
    directly to clone on boot.

bado clone --mac <mac> [ --hostname <name> ] --hardware <hardware> \
           --storageid <storageid> --autoclone

   Once a cloned images is uploaded to the Baracus server, it is automatically registered with the storage
   sub-system as a valid image storage object.
                                                                                                                 20
                                                                                      http://baracus-project.org
7.12 Build

  A new host entry for a system build can be added with bado build command. This is the combination of
  distribution and configuration container information. Some of the more common command examples are
  listed below.

  NOTE: In order to build a system, you must first create network install sources as detailed in Section 10
  and define configuration containers as defined in Section 8.

  The most basic method of creating a new host build entry is by only defining hostname, ip, mac and
  profile.
bado build --mac <mac> --hostname <name> --ip <addr> --profile <prof>

  If the environment uses DHCP with IP pooling and does not have static IP address, the --ip <addr> should
  be set to “dhcp” as shown below:
bado build --mac <mac> --hostname <name> --ip dhcp --profile <prof>

  Note that if only --profile <prof> is used, the profile itself must contain lines for
...
distro=<distro>
addon="<add1> <add2> ..."
hardware=<hw>
autobuild=<template>
module="<mod1> <mod2> ..."

  If these definitions are not within the <prof> then they should be specified on the command line.
bado build --mac <mac> --hostname <name> --ip <addr> --profile <prof> \
  [--hardware <hw>] [--distro <distro>] [--autobuild <template] \
  [--addon <add1> --addon <add2> ... ] [--module ”<mod1> <mod2> <...>” ]

  Excluding the --autobuild <template> will force the installer to use interactive mode (e.g.
  yast/kickstart).

  Please note that there is an implicit precedence in the way settings are applied.

  First applied are all the settings provided within the --profile <prof>, then the settings from
  --distro <distro> and --hardware <hw> configurations and finally, any command-line parameters.
  This way, precedence is lowest to highest by largest to smallest scope.

  If the --profile <prof> contains lines with distro= and/or hardware= and the command-line also
  has --distro and/or --hardware, arguments specified, the command-line configurations will be used
  instead. This is not additive - it is either or, not the sum of the two conflicting configurations.

  Similar conflict resolution is also used for the profile line containing module=”<mod1> <mod2> <...>”
  and --module= passed on the command-line; the command-line value, if present, will be used
  exclusively.




                                                                                                              21
                                                                                          http://baracus-project.org
7.12.1          Build and remote access

      Baracus supports three main methods of remote access during build time: vnc, ssh and serial console.

      Serial console access is configured with the bado build command with the --serialtty and
      --serialbaud options.
  bado build ... --serialtty=”<tty>” --serialbaud=”<baud-rate>”

      Common serial tty(s) are ttyS0 and ttyS1. Common serial baud rates are; 9600, 19200, 38400, 57600,
      and 115200.

      Vnc access is configured with the bado build command with the --usevnc and --vncpass options.
  bado build ... --usevnc --vncpass=”<vnc-password>”

      ssh access is configured with the bado build command with the --usessh and --sshpass options.
  bado build ... --usessh –sshpass=”<ssh-password>”



7.12.2          Build and remote logging
Baracus supports consolidated remote build logging for Linux.

      To enable remote build logging, edit

      /etc/sysconfig/baracus

      and set the REMOTE_LOGGING option to yes.
  REMOTE_LOGGING=”yes”

      With this modification, an invocation of service baracusd restart ( 2.5 Starting Services), all subsequent
      invocations of bado build will then cause build logs to be sent to

      /var/spool/baracus/logs/remote/<hostname>/<date>.log

      Note: remember to manage your disk space




                                                                                                                   22
                                                                                        http://baracus-project.org

7.12.3          Build and Network-hosted storage
Baracus supports builds using network-based root file systems (NFS root or iSCSI). Network-based file systems
are used to support clusters of diskless nodes, when local disks are allocated to specific NON-OS storage
functions, or to provide file-system overlay support.

      Build to Network-hosted storage is currently only supported for iSCSI and NFS root. For NFS root installs,
      the supported distro is SLES 11 SP1. An example command line for initiating an NFS root build is:
  bado build --mac 00:..:00 --distro sles-11.1-x86 --profile default \
             --hardware default-nfs --autobuild sles-11.1-x86_64-nfs \
             --storageid <storageid>

      With this command line, an invocation of baracus build will then cause the installing node to use server IP
      and NFS share defined by the storage id provided via the parameter

      --storageid <storageid>

      Note that only diskless NFS root nodes are currently supported by SLES 11 SP1. NFS root nodes
      with local disks present (including Xen) are not currently supported for build. Native support for
      NFS root nodes with disks (including Xen) will be supported in Baracus in a future release and is
      also expected by SLES 11 SP2 and RHEL 6.




                                                                                                               23
                                                                                     http://baracus-project.org


                                       8 XEN Support
8.1 Xen PXE boot Support
    Native Xen does not inherently support PXEboot and therefore does not function with Baracus out-of-the-
    box. In order to provision Baracus-PXEboot support in Xen, it is necessary to install a PXEboot-enabled
    Xen bootloader script and to reference that script as bootloader for Baracus-enabled Xen VM nodes.

    The Xen bootloader script package pypxeboot.baracus can be found in the noarch directories of the
    Baracus-supported host systems here:

   http://download.opensuse.org/repositories/systemsmanagement:/baracus/

   To deploy Xen VM nodes with Baracus, download the appropriate pypxeboot.baracus bootloader script
   package from the build service and install it on the Suse Xen Dom0 host.
rpm -i pypxeboot.baracus -0.0.1a-1.1.noarch.rpm



8.2 Xen DHCP Configuration
    The pypxeboot Xen bootloader script behaves as a proxy DHCP client for a booting Xen virtual machine.
    The Xen bootloader performs the PXEboot network I/O in the context of the Xen host, prior to any virtual
    network device becoming present on the associated LAN or vLAN. Special care must be taken to ensure
    that the DHCP server is properly configured to broadcast DHCP responses, allowing the PXEboot proxy
    to receive the response via the Xen host's physical LAN interface.

   If using the standard ISC DHCP server, add the following line to the subnet section of the
   /etc/dhcpd.conf file:
always-broadcast on;


   If using the dnsmasq server for DHCP, add the following line to the /etc/dnsmasq.conf file:
dhcp-broadcast=#bootp




                                                                                                            24
                                                                             http://baracus-project.org

8.3 Xen VM Configuration

    A sample of a Xen-pxeboot virtual machine configuration file “/etc/xen/vm/xen_pxe_client“ is
    shown below:

name="Xen_PXE_client"
description="Xen_PXE_client"
uuid="bef70bd0-6413-0d1b-4f4a-c23765f9b09e"
memory=512
maxmem=512
vcpus=1
on_poweroff="destroy"
on_reboot="restart"
on_crash="destroy"
localtime=0
keymap="en-us"
builder="linux"
extra=" "
disk=[ 'file:Xen_PXE_Client_disk0.raw,xvda,w', ]
vif=[ 'mac=00:16:3e:00:00:a0,bridge=br0', ]
vfb=['type=vnc,vncunused=1']
bootloader="/usr/bin/pypxeboot.baracus"
bootargs=vif[0]

   Boot the Xen node conventionally. e.g.
xm create Xen_PXE_client




                                                                                                    25
                                                                                   http://baracus-project.org


                                  9 Multicast Channels
9.1 Create a multicast channel
    To deploy a raw disk image to more than one node at the same time via multicast you first need to setup
    a multicast channel with the bamcast command:

bamcast create --name <channelid> --storageid <storageid> --dataip <ip> \
               --rdvip <ip> --interface <network interface> \
               --ratemx <integer> --mrecv <integer>

   Where

   <name> a unique, human readable identifier for the multicast channel

   <storageid> a valid storage object of type “image”

   <dataip> is the multicast ip address for data channel

   <rdvip> is the multicast ip address for the control connection

   <interface> is the network interface to use for the channel, usually the default ethX

   <ratemx> is the max bite rate to use on the multicast channel

   <mrecv> the minimum number of receivers required to start sending the data on the channel


9.2 Listing registered channels

   To list currently registered multicast channels:
bamcast list      [ --filter name::'*partial*'             | --filter name::specific ]

9.3 Channel details

   To show the details of a specifc multicast channel:
bamcast detail --name <channelid>

9.4 Removing registered channels

   To remove a registered multicast channel:
bamcast remove --name <channelid>




                                                                                                          26
                                                                                      http://baracus-project.org


                        10           Network Install Sources
   In order to use the Baracus build capabilities, you first need to have an available network install source.
   Baracus provides the basource command to manage these sources. A Baracus network install source
   supports automatic fetching of OS distribution ISOs, the creation of network install sources and the
   manipulation of the network services as needed to provide access to the newly generated installation tree.
   Additionally, Baracus allows configured sources to be enable and disabled with ease.


10.1       Basource help

   The basource help command can take an optional subcommand. This may be all you need for
   documentation.
basource help [ <command> ]

10.2       Locating distribution ISOs

   If you do not already have the required ISO files local in the ~baracus/isos directory, you can have
   Baracus automatically download them as discussed in the next section.

   However, if you already have operating system ISOs downloaded, you can save a tremendous amount of
   time by making them available to Baracus in this directory:

   ~baracus/isos

   Then you can use basource add with the --check option. This directs Baracus to verify the md5 for
   the related ISOs.
basource add --check --distro <distro-name>                  [ --addon <id> … ]

   If the checksum is found to be incorrect, Baracus will abort the creation of the network install source and
   inform you which ISO(s) failed.

   NOTE: In some cases, most notably where distribution names for ISOs are not well defined, you may need
   to edit:

   /etc/baracus/distros.d/.../distros.xml




                                                                                                                 27
                                                                                         http://baracus-project.org
10.3          Creating a network install source

   To create a network install source, use the basource add command:
basource add --distro <distro-name> [--addon <id> ...]

   Create a new build source with verbose output
basource add --distro <distro-name> [--addon <id> …] --verbose

   The optional –addon <addon-name> or --dud <dud-name> allows for the addition of add-on products or
   driver update disks to the base distribution. This option can be specified multiple times.

   Automatic download is accomplished with --isos. You will be prompted for credentials if needed.
basource add --isos [--proxy] --distro <distro-name> [--addon <id> ...]

   For the creation of network install sources related to Windows® operating systems, a one time only
   special sequence of steps, in an existing Windows running instance, must be performed to create a
   Windows Pre-Execution environment (See Appendix for more details)


10.3.1         Addons
       Source addons are usually distribution product addons like Novell's High Availability addon (sles-11.1-ha-
       x86_64). They are dependent on base distributions and cannot be installed without their required base.


10.3.2         DUDs
       DUDs or Driver Update Disks are distribution and/or hardware provided updates to a distribution that
       provide newer drivers for hardware support not available at time of initial distribution release. These
       drivers, particularly disk and network, can be very troublesome as they themselves are required for
       system installation and must be updated in the installer kernel and made available during installation.
       Baracus supports DUDs as additional source types and streamline this once daunting process. As a
       normal source type they can be added and remove just like an addon.
basource add --distro sles-11.1-x86_64 --dud sles-11.1-esrt2-x86_64

       To include a DUD during an install you simple need to specify it in your hardware container as a
       “driverupdate”. This can be done at hardware creation with the --driverupdate “<DUD name>” option to
       baconfig add hardware. An example is as follows:
baconfig add hardware --name ibmX365 --bootargs “acpi=on selinux=0 apm=off” \
                      --rootdisk “/dev/sda” --rootparg “/dev/sda”           \
                      --driverupdate “sles-11.1-esrt2-x86_64”               \
                      --description “X365 hardware class with ESRT DUD”

    Then specify that hardware type in your bado build command line.
bado build --hostname <host> --mac <mac> --distro sles-11.1-x86_64 ... \
            --hardware ibmX365




                                                                                                                 28
                                                                                         http://baracus-project.org

10.4       Listing available install sources

   To list the distributions and addons currently available as network install sources, use the basource list
   command:
basource list [ base | addon ] [ --distro <'*partial-name*'>] [ --all ]

   To see the list of sources presently available for network install with:
basource list [ --distro <'*partial-name*'>] [ --all ]

   To see a complete list of base distributions or add-ons that Baracus is able to manage and build with:
basource list [ base | addon ] [ --distro <'*partial-name*'>]

   If specified, the --all option will show distributions that Baracus has information about (in the badistro.xml
   file) even if they are not already made available as network install sources.


10.5       Removal of network install sources

   Build sources can be removed from the pool of available install sources with the basource remove
   command:
basource remove --distro <distro-name> { [ --addon <id> ... ] | [--all] }

   The optional --addon <id> allows for the removal of specific add-on products. This option can be
   specified multiple times. Also note that if a base distribution has addons available, it cannot be removed
   without first removing all the addons as install sources, therefore Baracus provides the --all option to
   remove all addons and a base distribution from sharing.


10.6       Managing install sources

   Build sources can also be dynamically enabled and/or disabled. This is very helpful for enforcing
   maintenance or black-out windows.
basource disable { --distro <name> | --addon <name> }
basource enable { --distro <name> | --addon <name> }

   It is also very helpful to get a full view of the current state of a given build source. This can be done with
   the basource verify command:
basource verify         { --distro <name> | --addon <name> }

   There is also a command to view Baracus internal representation details about a distribution which may
   occasionally be helpful:
basource detail         { --distro <name> | --addon <name> }




                                                                                                                    29
                                                                                  http://baracus-project.org

10.7       Manual override of service status

   Although Baracus restarts network services as needed to make the addition and removal of share active
   upon command completion, there may be instances where you would like to restart or stop services
   yourself. Baracus provides a wrapper for this:
basource service --start             # restart defaults              [ SHARE_TYPE and dhcpd ]

basource service --stop               # stop defaults                [ SHARE_TYPE and dhcpd ]

basource service --start <type> [...]                # restart specified service(s)

basource service --stop         <type> [...]         # stop specified service(s)

   Manipulating the status of these services, which Baracus depends on, can lead to unexpected results and
   is not advised.




                                                                                                           30
                                                                                       http://baracus-project.org


                       11          Configuration Containers
   Before we can direct Baracus to do much more than boot nodes from localdisk or network, we need to
   describe some configuration information about the nodes being managed.


11.1        Configuration overview

   Baracus provides several configuration containers to help describe nodes, software, additional install
   scripts, and how to combine them. The container types are named Hardware, Autobuild, Module and
   Profile.

   All instances of these containers are stored in the Baracus database, can be enabled or disabled, and are
   version controlled. Only one version of a specific container can be enabled at any given time. By default,
   the enabled version of a container is used in commands in which they are referenced.

   Additionally, Baracus supports certifications of configuration containers against operating system
   distributions. These certifications are very useful in enforcing standards. For instance you can certify a
   particular hardware container against a specific distribution. By doing so, only that combination of
   hardware and operating system will be allowed to be built.

   Additionally, modules support --mandatory and --optional flags via the baconfig command. By
   setting a module as mandatory, it will force that module to be included in all certified builds. Modules that
   are marked as mandatory cannot be disabled and the mandatory flag is global in that modules remain
   mandatory even through version changes. All modules are optional by default.

   Baracus also provides enhanced TFTP services via the Baracus database file system. This “TFTP file
   system” can also be directly exposed using the baconfig command described in this chapter. Direct
   manipulation of these TFTP files by administrators is not advised and can lead to unexpected results.


11.2        baconfig help

   The baconfig help command can take an optional subcommand, sometimes two. This may be all you
   need for documentation.
baconfig help [<command>]

baconfig help { add | update } <type>

   Where:

   <command> can be add, detail, export, list, remove, or update.
   <type> can be profile, module, hardware, autobuild, or tftp.




                                                                                                                31
                                                                                         http://baracus-project.org
11.3       Creating a configuration container

   To create a new entry use baconfig add on profile, module, autobuild and tftp types.
   Newly added containers are enabled by default.
baconfig add <type> --name <name> --file <file> [--enable | --disable] \
         --description ”text”

   The baconfig add command for the hardware type will be described later.


11.4       Listing configuration containers

   For listing entries, use baconfig list and optionally pass a string for an exact match or one with an
   asterisk for a partial or pattern match.
baconfig list <type> [<exact>|'*<partial>*'] [--all]

   For types that support version, the disabled entries will not be displayed unless --all is specified.


11.5       Removing configuration

   To remove an entry use baconfig remove.
baconfig remove <type> <name> [--version <#>]

   Be careful with types that support version. If --version <#> is not specified on remove invocation, all
   versions of container <type> named <name> shall be removed.


11.6       Configuration detail

   Details on a given entry can be seen using baconfig detail and if the type supports versions, the
   enabled entry is displayed.
baconfig detail <type> <name> [--version|--all]

   To see disabled entries, you can specify --version for a specific entry or --all to see all versions.


11.7       Exporting configuration to a file

   For those entries for which detail is refused because the content exceeds a reasonable console size limit,
   you have the ability to extract the content to a file using baconfig export.
baconfig export <type> --name <name> --file <file> --version

   The baconfig export command is particularly helpful when dealing with tftp type files as these may
   be binary. Also, the baconfig export command is unavailable for the hardware type.




                                                                                                                32
                                                                                     http://baracus-project.org
11.8       Updating configuration or adding a new version

   New versions are created using baconfig update and passing it the --file to use for the new
   content (with hardware pass the non-enable and non-description related values to be modified). New
   versions are disabled by default.
baconfig update <type> --name <name> --file=<file> [--enable|--disable] \
      [--description ”text”]

   Enabled state and/or description information can be modified without creating a new version, just do not
   pass a new file or modify anything other than state and/or description.
baconfig update <type> --name <name> --version <ver> \
     { [--enable|--disable] | [--description ”text”] }

11.9       Container types

11.9.1       Profile Containers
   Profiles are defined sets of configuration variables. Most commonly they are things like network setting for
   individual networks: netmask, default gateway, dns, etc., although they can extend to almost anything
   including timezone, keyboard and even Baracus configuration specific items like autobuild, hardware,
   distribution, addons and modules.

   Baracus supports versions for profiles. All baconfig commands (e.g., add, detail, export, list,
   remove, or update) are available for use with the profile type.


11.9.2       Module Containers
   Modules are automated post-install scripts that get executed as part of the standard install post section.
   They have been modularized so that they can be reused and dynamically linked to individual host entries.
   An example might be a module that installs some site specific software post build.

   Baracus supports versions for modules. All baconfig commands (e.g. add, detail, export,
   list, remove, or update) are available for use with the module type.

   Baracus also supports operating system scoping, or certification, of modules for use with particular
   distributions using the --cert, --addcert and --rmcert flags via the baconfig command.

   Baracus supports flagging modules as mandatory for a distribution with --mandatory, or removing this
   flag with --optional. This flag indicates that the module is to be delivered as part of the operation
   system install even if the user omits it from the build recipe.
baconfig add module --name <name> --file <file> \
     [--cert <distro> ... [--mand <distro> ...]] \
     [--enable|--disable] [--description ”text”]

   and, for updating an existing module:
baconfig update module --name <name> --version <ver> \
     [--addcert <add_dist> ... [--mand <add_dist> ...]] \
     [[--opt <add_dist> ...] --rmcert <rm_dist> ...] \
     < [--enable|--disable] | [--description ”text”] >
                                                                                                              33
                                                                                     http://baracus-project.org
11.9.3       Hardware Containers

   Hardware configurations enforce build standards for a particular piece of hardware. These include things
   like root disk definitions, boot parameters and any non-distribution hardware drivers that may be required.

   Baracus supports versions for hardware. The baconfig commands add, detail, list, remove or
   update are available for use with the hardware type. The export command is not supported.

   Baracus also supports certification of hardware for use with particular distributions using the --cert
   option with the baconfig add command, and --addcert and/or --rmcert flags with the baconfig
   update command. This allows enforcement of certifications on builds.

   The usage of baconfig add hardware is somewhat more complex than for other configuration
   containers (because the add is not a file "import"):
baconfig add hardware --name <id> --bootArgs “text” \
             --rootdisk “/dev/<disk>” --rootpart “/dev/<partition>”                            \
             [--description “text”] [--driverupdate “rpm list”] \
             [--cert “<distro1> <distro2>...”]

   Fortunately, some have already been provided as examples.
baconfig detail hardware default

   For further reference, preloaded hardware profiles are loaded by this script on database start-up:

   /usr/share/baracus/scripts/baconfig_load_hardware

   Certifications can be added and removed via the baconfig update subcommand with the --addcert
   and --rmcert options.

   Adding additional certifications
baconfig update hardware --name <id> --addcert ”<distro1> <distro2>”

   Removing certifications
baconfig update hardware --name <id> --rmcert ”<distro1> <distro2>”




                                                                                                            34
                                                                                          http://baracus-project.org

11.9.4       Autobuild Containers

   In Baracus, all native builder file formats (autoyast, kickstart, preseeding, unattended, and jumpstart)
   are variablized templates that are used at build time to dynamically create host specific build files.

   Baracus supports versions for autobuild files. All baconfig commands (e.g., add, detail, export,
   list, remove or update) are available for use with the autobuild type.

   Baracus also supports certification of autobuild files for use with particular distributions using the --cert,
   with the baconfig add command.
baconfig add autobuild --name <name> --file <file> \
     <[--cert <distro> ...] [--enable|--disable] [--description ”text”]>

   and using --addcert, and --rmcert flags with the baconfig update command:
baconfig update autobuild --name <name> --version <#> \
     <[--addcert <add_dist> ...] [--rmcert <rm_dist> ...] \
     [--enable|--disable] | [--description=”text”] >

   If --version <#> is omitted then the 'enabled' version is updated (status and description); if no
   --version <#> is specified and no enabled version is found for the container, an error will be reported.

   Certification is version transparent and applies to all versions.

   For further reference, preloaded autobuild profiles are loaded by this script on database start-up:

   /usr/share/baracus/scripts/baconfig_load_autobuild




                                                                                                                    35
                                                                                         http://baracus-project.org

11.9.5       File

   The file type is not really a container but a file database store used to secure mainly those files like kernel
   and ramdisks necessary for bootstrapping payloads.

   Due to the limitations of legacy TFTP, Baracus uses its own enhanced TFTP server directly accessing the
   files stored in the Baracus database. baconfig <command> file supports all commands (e.g., add,
   detail, export, list, remove or update) to expose and manipulate these files directly.

   Direct access and manipulation of these files is discouraged as these files are created and maintained by
   the basource and bado commands and direct manipulation can lead to unexpected results.

   Still, having access to see what is available with the baconfig list file subcommand, and viewing
   the contents with either baconfig detail or baconfig export may prove helpful.
baconfig list file

baconfig detail file <filename>

baconfig export file --name <filename> --file /tmp/<file>

   Note the use of the /tmp directory for the output of the baconfig export command. The output
   directory must be writable by the 'baracus' system user.

   Side note: hardware inventory, image installation and wipe logs are also stored in this database file
   system.

   The database does not yet support versions or certifications for file type.




                                                                                                                36
                                                                                    http://baracus-project.org


                                   12          Repositories
   Baracus also assists with the streamlining of auxiliary repositories for customized package deployment
   during provisioning. The barepo command is the tool used to create, add, remove and verify
   repositories.

   Currently supported repository types are YUM for rpm packages and APT for Debian deb packages.


12.1       barepo help

   The barepo command has subcommand level help so this may be all you need for documentation
barepo help [<subcommand>]

12.2       Creating a repository

   Creating new Baracus repositories can be done with the barepo create subcommand as shown
   below:
barepo create --repo <repo-name> --distro <distro> --packages [rpm-packages]

   An actual example might look like the following:
barepo create --repo kernel-update --distro sles-11.1-x86_64 \
              --packages “kernel-default-2.6.27.21-0.1.2.x86_64.rpm”

12.3       Adding packages to a repository

   If you already have a Baracus repository, you can modify it by adding new RPM packages with the
   barepo add command. Packages can be added either one at a time or list them all in the same
   command line. Shell wild card substitution also works for package names.
barepo add --repo <repo-name> --distro <distro> --packages <rpm-packages>

   After new packages are added, barepo update is automatically called internally to make them available.


12.4       Listing available repositories

   Baracus repositories can be listed with barepo list to see the repositories available.
barepo list [ --repo <repo-name> | --repo '*partial-name*' ]

   Baracus repository RPM files available can also be listed using barepo detail
barepo detail --repo <repo-name>




                                                                                                            37
                                                                                      http://baracus-project.org
12.5       Removal of a repository

   Baracus repositories can also be completely removed with the barepo remove command:
barepo remove --repo <repo-name>

   This will remove the http configuration related to the share and all the files in the ~baracus/byum/<repo-
   name> directory so use with caution.


12.6       Verification and update of a repository

   The listing and signature of a repository can be verified correct with the barepo verify command:
barepo verify --repo <repo-name>




                                                                                                                38
                                                                                    http://baracus-project.org

            13          Managing Node Related Information
   This section describes the different states that nodes can have associated with them and how to access
   information related to those states.


13.1 Defining nodes

   A node is a device with a MAC address that is network boot capable. Baracus might also have been
   provided a hostname as a more convenient human handle to refer to this device. Nodes have Baracus
   state information associated with them so that Baracus knows how to direct them on network boot; with
   the controller and right information nodes can be powered on and off as discussed in section 4. In
   Baracus, nodes also have an associated status so they can be enabled or disabled.


13.2 bahost help

   The bahost help command accepts an optional subcommand. This may be all you need for
   documentation.
bahost help [<command>]

13.3 Pre-staging a node entry

   As mentioned, Baracus will register a node when it gets a network boot request from it. Pre-registering
   can be done with the bahost add command as follows.
bahost add --mac <mac> [ --hostname <name> ]

   If you include --hostname <name> it can be used in other commands to refer to this node that is
   otherwise uniquely identified by its <mac> address.


13.4   Listing known node information

   Registered nodes are maintained in the Baracus database. Useful information about these nodes can be
   listed with bahost list subcommands.

   To list all known nodes use the bahost list nodes command:
bahost list nodes [ --filter <fancy> ]

   To see the nodes' associated autobuild templates use the bahost list templates command:
bahost list templates [ --filter <fancy> ]

   Finally, to see the states associated with each node use bahost list states command:
bahost list states [ --filter <fancy> ]




                                                                                                             39
                                                                                    http://baracus-project.org
13.5   Fancy filtering on queries

   If in the rest of this documentation you see --filter <fancy> try to recall this syntax

   for mac filtering:
       --filter mac::<exact> | --filter mac::'*<partial>*'

   or hostname filtering:
       --filter hostname::<exact> | --filter hostname::'*<partial>*'

13.6   Setting a nodes administrative state

   Nodes can have one of three administrative states: (enable,disable)
bahost enable { --mac <mac> | --hostname <name> }
bahost disable { --mac <mac> | --hostname <name> }

   Nodes in the disable state will be served a pxewait (indefinite wait at "boot:" in PXE menu) when they next
   boot.

   Also, if the nodes “active” status is anything other than enabled you may want to invoke the bahost
   enable command to make sure Baracus is ready to boot manage that node.


13.7   Purging all node information

   All node mac, hostname, related actions, and any logs from inventory, wipe or image can be purged from
   Baracus with the bahost remove command:
bahost remove { --mac <mac> | --hostname <name> }

   NOTE: This purge does not remove the command history or other database logged events such as state
   transitions for the node.

   If you are decommissioning a system and have gone through a secure system wipe, you might like to
   check the wipe log with the baconfig detail tftp command before purging.
baconfig detail tftp <mac>.wipelog

13.8   Displaying node details

   To see details about how a node would build or what target disk image it would use to network boot use
   the bahost detail node command:
bahost detail node { --mac <mac> | --hostname <name> }

   To see the inventory (if collected) use bahost detail inventory command:
bahost detail inventory          { --mac <mac> | --hostname <name> }

   To export the inventory you could use the baconfig export tftp command:
baconfig export file --name <mac>.inventory                 --file /tmp/<mac>.inventory
                                                                                                            40
                                                                                      http://baracus-project.org
13.9   Baracus states for nodes

   Baracus has two types of state information associated with each node to determine what to do with the
   node on its next network boot. First, as mentioned in 9.6, nodes have an administrative "active" state
   related to any administrative invocation of bahost { enable | disable }. Second, nodes have an
   operational "state" which is partly controlled by bado commands and partly by transitions based on
   completion of tasks, automated modification, while in a given "state."

   Note: These states are not boot directives themselves but sometimes will automatically transition boot
   directives. For example a state change from building to build will automatically update the boot directive
   from build to boot.

   These operational states include:

   found node mac just discovered inventory workload served

   register node delivered inventory to Baracus server

   building node retrieved its "build" workload and is in progress

   built node finished building and called back with mac, hostname, uuid expected

   spoofed node finished building and called back with incorrect identifiers

   wiping node retrieved its "diskwipe" workload and is in progress

   wiped node successfully finished wiping and did log upload

   wipefail node finished wiping with failed status and did log upload

   imaging node retrieved its "imaging" workload and is in progress

   imaged node successfully finished imaging the did log upload

   imagefail node finished imaging workload with some failure and did log upload

   The uploaded logs for completed states (e.g. built, imaged, and wiped) go into the baconfig tftp
   filesystem (even though TFTP is not used for the upload).

   There are also pxecurr and pxenext states, which should give administrators some idea of the last
   directive the node received from Baracus and what the next directive will be when the node next PXE
   boots.

   NOTE: currently the built and spoofed callback require a specific HTTP GET invocation in the post-install
   script portion of an automated build script. If a node was not built from a template based on one of the
   provided examples autobuild template this call back will not occur and the operational state will remain
   building. To use a template not based on one of our example please make sure to include the callback
   hook (see post install section of autobuild template for examples). Future releases will include this HTTP
   GET as an embedded "mandatory" module.

                                                                                                                41
                                                                                        http://baracus-project.org

                         14          Logs and Audit History
14.1 Historical state look-up

   The balog list states command can be used to determine the state of a system at any given point in
   time as shown below:
balog list states [ --filter <fancy> ] [ --verbose ]

   Recall the <fancy> filter was discussed here in § 13.5 Fancy filtering on queries.

   The --verbose option can be added to expose additional information.


14.2 Historical command look-up

   The balog list commands command can be used to review operations affecting a node, whether run
   by a user or a modification automated by Baracus, at any point in time as shown below:
balog list commands [ --filter <fancy> ] [ --verbose ]

   The --verbose argument can be added to expose additional information.


14.3 Exporting audit data

   The results from the balog commands for both states and commands can be exported to comma
   separated value (CSV) files for more advanced report generation as follows:

   Export state data:
balog export states --file <filename>.csv [ --filter <fancy> ]

   Export command data:
balog export commands --file <filename>.csv [ --filter <fancy> ]




                                                                                                               42
                                                                                  http://baracus-project.org

                 15           Appendix A – Baracus Hooks
In order to facilitate a high degree of integration with other management tools and frameworks, Baracus
provides a number of hooks for linking in automation scripts. A list of provided hooks is listed below.
    new_inventory_available
    node_in_pxewait
    verify_client_build_passed
    verify_client_build_failed
    node_in_mcastwait
    mcast_deploy_complete
    mcast_deploy_failed
    node_in_clone_ready
    image_deploy_complete
    image_deploy_failed
    clone_fetch_failed
    clone_fetch_complete
    ipmi_user_failed
    ipmi_user_complete
    wipe_disk_complete
    wipe_disk_failed

Baracus hooks work by executing user defined code when the hook is activated by some event. Hooks
are passed information that is communicated back to Baracus such as the MAC and IP of the device.
Additionally, the verify_client_build_passed hook has access to the hostname of the system.

All Baracus hooks are completely user definable and are located in the following directory:

~baracus/hooks/

An example of the verify_client_build_* hooks is documented below.

Systems that pass will trigger the following script to be run:

~baracus/verify_client_build_passed hostname IP UUID [MAC]

Systems that fail will trigger the following script to be run:

~baracus/verify_client_build_failed hostname IP UUID [MAC]




                                                                                                          43
                                                                                      http://baracus-project.org

                       16          Appendix B - distros.xml
  The basource command understands how to work with the operating system distributions and addons as
  defined in distros.xml

  /etc/baracus/distros.d/<directories>/distros.xml

  You can modify these files to suit your needs such as modification of an ISO name or addition of a new
  distribution. Also, you can add new files as required. With any change or addition you need to follow the
  following steps.

  Before modification you should run the hidden command:
basource purgedbofxml

  There may be warnings or errors related to the database with the distro being referenced as a foreign key.
  These should be safe to ignore unless you are modifying a related entry and in this case anything you to
  clean up and replace the entry will likely result in the loss of information related to a build or dependency.

  After modification you should run the hidden command:
basource prepdbwithxml




                                                                                                              44
                                                                                     http://baracus-project.org

           17          Appendix C – Creating WinPE Setup
  Support for the network installation of Microsoft Windows® 7, Windows Server® 2008 and the Windows
  Vista family of operating systems requires one time administrative work done outside of the scope of
  Baracus tools.

  You must follow these instructions before the first basource add invocation to add a Windows network
  install source.

  You need a running instance of one of the operation systems mentioned above and the Automated
  Installation Kit (AIK) available from Microsoft directly. We recommend using Windows 7 if it is available. If
  not, Windows 2008 and/or Vista would also work.

  Make sure you have samba running on the Baracus server and the helper cifs share available:
> grep winstall.conf /etc/samba/smb.conf
include = /etc/samba/winstall.conf
> service smb restart     # or 'start' if not already running
> smbclient -L localhost # look for winstall

  Then in the running instance of Windows that has AIK installed, you need to launch the AIK command-tool
  with administrator privileges (right-click on the menu item) and in that command shell, mount the share
  "winstall" and run "bawinstall.bat" as follows:
c: net use x: \\<baracus_ip>\winstall
x:
bawinstall.bat x

  This WinPE environment only needs to be created once for each architecture (32bit and 64bit). After
  these preliminary steps are taken Baracus is fully able to support the addition and serving of Windows
  operating systems as a network install source.




                                                                                                             45

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:3
posted:2/8/2012
language:
pages:45