Open Ethernet Networking (OpEN) API Guide and Reference Manual  3.6.0.3
OpEN API and Puppet

As part of the Broadcom Linux RPM distribution, Broadcom supplies a Puppet agent that runs on the switch. Puppet is a tool that automates infrastructure deployment. See http://www.puppetlabs.com for more information.

Prerequisites

It is assumed that the reader is familiar with the concepts of Puppet:

Installing the Puppet Agent

Broadcom Linux Distribution

The Puppet agent requires a number of RPMs to be installed in order for it to execute. To install the Puppet agent, first install RPM as defined in the Bootstrapping RPM section. Then use the rpm-install.sh helper script, described in the RPM Package Installation section, to install the Puppet agent and all of it's dependencies as shown below:

  (ICOS Routing) #linuxsh
  # cd /mnt/fastpath
  # ./rpm-install.sh puppet mypath 10.27.9.99
  # ......
  # rpm -q puppet
  puppet-3.1.1-1.1.el6.noarch
  # which puppet
  /bin/puppet
  # exit
  (ICOS Routing) #

Ubuntu Linux Distribution

Follow the instructions below to install Puppet and all of its dependencies:

  unix% sudo apt-get install puppet

Installing the Ruby SWIG

The Puppet agent on the switch requires SWIG files from the OpEN API to be built and installed. These are installed on the switch by default, and no further action is required if you are using an unmodified OpEN API.

If you have modified the OpEN API then you should ensure the Ruby language bindings are up to date. See the Ruby section of the OpEN API and Language Bindings section for further details.

Setting the hostname

The default switch hostname is localhost. This should be changed to something unique for the host by editing the /etc/sysconfig/network file and then executing the command below. Note that if you change your hostname then you must update your /etc/hosts file as described in section Configuring Name Resolution below.

  # . /etc/sysconfig/network; hostname $HOSTNAME

Configuring Name Resolution

Puppet requires that name resolution is configured correctly. Note that your Puppet server must also be able to resolve the name of all the Puppet agents, an so may require similar configuration.

Name resolution could be done by configuring DNS as described in section DNS Configuration. You should then ensure that your /etc/resolv.conf file contains a search entry (e.g. search example.com), that you have run crlinks.sh, and that your hostname is in your DNS server.

Alternatively you can configure name resolution using the /etc/hosts files. To do this add your hostname and Puppet server name as follows. Note that this assumes your Puppet server is called puppet, your hostname is tor1 and that your domain is example.com.

  10.11.12.13 puppet puppet.example.com
  10.11.12.14 tor1 tor1.example.com

Note that you will also need to add a search entry to your /etc/resolv.conf file (e.g. search example.com).

Once name resolution has been configured, you should ping your Puppet server to validate connectivity.

Configuring the Puppet Agent

Modifying /etc/puppet/puppet.conf

The server setting in the /etc/puppet/puppet.conf file should be modified to match your configuration. The server should be specified as a hostname, e.g. mypuppet.example.com. This requires that name resolution is configured (see the Configuring Name Resolution section).

Basic Puppet Server Configuration

To facilitate testing, a simple resource should be created on the Puppet server for the new node. For example, if your new node is called tor1.example.com then add the following to the /etc/puppet/manifests/site.pp file :

 node 'tor1.example.com' {
   file {'testfile':
     path    => '/tmp/testfile',
     ensure  => present,
     mode    => 0640,
     content => "Hello World",
  }
}

This will cause the /tmp/testfile to be created when the Puppet agent is started on the switch.

Updating the System Time

The Puppet agent requires that the time be synchronized with the Puppet server. The simplest way to do this is to synchronize with a central time server using NTP. To synchronize the Puppet agent on the switch add your time servers to /etc/ntp/step-tickers and then use the ntpdate server. This will synchronize the switches time to your NTP server each time the switch boots.

  (ICOS Routing) #linuxsh
  # cd /etc/ntp
  # echo 10.11.12.13 >> step-tickers
  #
  # chkconfig ntpdate on
  # /etc/init.d/ntpdate start
  ntpdate: Synchronizing with time server:       [ OK ]
  # date
  Sat Apr 27 03:14:26 UTC 2013
  #
  # exit
  (ICOS Routing) #

Certification Validation and Server Connectivity

The following command should be issued on the switch to configure connectivity to the Puppet server. Note that the first time we run this command we expect to fail with the output below:

  # puppet agent --test
  info: Creating a new SSL certificate request for tor1.example.com
  info: Certificate Request fingerprint (md5):
  FD:E7:41:C9:2C:B7:5C:27:11:0C:8F:9C:1D:F6:F9:46
  Exiting; no certificate found and waitforcert is disabled
  #

If this is not the first time you have registered your switch with the Puppet server then you may get an error about the agent and server's certificates being different. Follow the instructions in the error message to remove the certificate from the switch and server and then run puppet agent --test again. Any other error messages from this command should be investigated and resolved before moving forward.

Assuming you get the above output, your Puppet server should now contain a certificate request for your new node, tor1.example.com in the above example. You must log onto the Puppet server and sign the certificate, e.g.:

  server% puppet cert list
  "tor1.example.com" (FD:E7:41:C9:2C:B7:5C:27:11:0C:8F:9C:1D:F6:F9:46)
  server%
  server% puppet cert sign tor1.example.com
  notice: Signed certificate request for tor1.example.com
  notice: Removing file Puppet::SSL::CertificateRequest tor1.example.com at
  '/etc/puppet/ssl/ca/requests/tor1.example.com'
  server%

You should now validate connectivity from the Puppet agent to the Puppet server again:

  unix% puppet agent --test
  Info: Caching certificate for tor1.example.com
  Info: Caching certificate_revocation_list for ca
  Info: Retrieving plugin
  Info: Caching catalog for tor1.example.com
  Info: Applying configuration version '1369180860'
  Notice: /Stage[main]//Node[tor1]/File[testfile]/content:
  Info: FileBucket adding {md5}8f380a32018d48d9f0f28757ds
  Info: /State[main]//Node[tor1]/File[testfile]: Filebucketed /tmp/testfile to
  puppet with sum 8f380a32018d48d9f0f28757ds
  Notice: Finished catalog run in 0.22 seconds
  unix%

If your output does not look similar to the above then you should investigate and resolve any errors.

Assuming you have no errors, you should now have a file called /tmp/testfile with contents "Hello World".

Starting the Puppet Agent

To run the Puppet agent in single shot mode, use the puppet agent --test command as described above. To run the Puppet agent as a service that gets started on each boot, use the following puppet command:

  # puppet resource service puppet ensure=running enable=true
  Notice: /Service[puppet]/ensure: ensure changed 'stopped' to 'running'
  service { 'puppet':
    ensure => 'running',
    enable => 'true',
  }
  #

Note that by default the Puppet agent will only check its configuration every 30 minutes. To modify this, change the runinterval value in the /etc/puppet/puppet.conf file.

Example Puppet Netdev Provider

Netdev Provider from DevOps community

As an example of the Puppet and OpEN API usage, Broadcom has developed the Netdev provider for the netdev_device, netdev_interface, netdev_l2_interface, netdev_lag and netdev_vlan features. Netdev is a vendor-neutral network abstraction framework developed by Juniper Networks and contributed freely to the DevOps community. More information can be obtained from https://github.com/puppetlabs/netdev_stdlib. NOTE: The Netdev provider supports Netdev corresponding to the following commit: https://github.com/puppetlabs/netdev_stdlib/commit/4ecc128cfc3fd057c49c4d709fc752fb4230437e (March 29, 2013).

For further information on how to install the base Netdev files, and the Broadcom Netdev implementation, see the Netdev Provider from DevOps community section.

Netdev Provider from Broadcom

As an example of the Puppet and OpEN API usage, Broadcom has developed the Netdev provider for the netdev_config_script feature. CLI text based configuration is pushed from Puppet and applied on ICOS based devices.

For further information on how to install the Broadcom Netdev implementation, see the Netdev Provider from Broadcom section.