xCAT/xcat-core
2
0
Fork 0
mirror of https://github.com/xcat2/xcat-core.git synced 2025-05-29 09:13:08 +00:00
Code Issues Releases Wiki Activity

Refine the Cumulus Linux Section of the Doc (#4249)

Browse Source 
* No content in the switches subdirectory in docs, remove

* Change the Network topic to Networking

* Refine and reformat the Cumulus Linux documentation
This commit is contained in:
Victor Hu 2017-11-16 04:56:29 -05:00 committed by yangsong
parent 7f3f7bec5d
commit c5bf988887
7 changed files with 89 additions and 64 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

1
docs/source/advanced/index.rst
View File

@ -23,6 +23,5 @@ Advanced Topics
restapi/index.rst
security/index.rst
softlayer/index.rst
switches/index.rst
sysclone/index.rst
zones/index.rst

4
docs/source/advanced/networks/index.rst
View File

@ -1,5 +1,5 @@
Networks
========
Networking
==========
.. toctree::
:maxdepth: 2

8
docs/source/advanced/networks/onie_switches/os_cumulus/install.rst
View File

@ -12,12 +12,16 @@ xCAT provides support for detecting and installing the Cumulus Linux OS into ONI
The mac address of the switch management port is required for xCAT to configure the DHCP information and send over the OS to install on the switch.
**[small clusters]** If you know the mac address of the management port on the switch, create the pre-defined switch definition providing the mac address. ::
**Small Clusters**
If you know the mac address of the management port on the switch, create the pre-defined switch definition providing the mac address. ::
mkdef frame01sw1 --template onieswitch arch=armv71 \
ip=192.168.1.1 mac="aa:bb:cc:dd:ee:ff"
**[large clusters]** xCAT's :doc:`switchdiscover </guides/admin-guides/references/man1/switchdiscover.1>` command can be used to discover the mac address and fill in the predefined switch definitions based on the switch/switchport mapping.
**Large Clusters**
xCAT's :doc:`switchdiscover </guides/admin-guides/references/man1/switchdiscover.1>` command can be used to discover the mac address and fill in the predefined switch definitions based on the switch/switchport mapping.
#. Define all the switch objects providing the switch/switchport mapping: ::

22
docs/source/advanced/networks/onie_switches/os_cumulus/manage.rst
View File

@ -4,7 +4,19 @@ Switch Management
Switch Port and VLAN Configuration
----------------------------------
xCAT expects the configuration for the front-panel ports to be located at ``/etc/network/interfaces.d/xCAT.intf`` on the switch. The ``configinterface`` postscript can download an interface configuration file from the management node. Place the configuration file in the directory ``/install/custom/sw_os/cumulus/interface/`` on the management node. It will first look for a file named the same as the switch's hostname, followed by the name of each group, followed by the word 'default'. If the postscript cannot find a configuration file on the management node, it will set all the ports on the switch to be part of VLAN 1. See the Cumulus Networks documentation for more information regarding advanced networking configuration. ::
xCAT places the front-panel port configuration in ``/etc/network/interfaces.d/xCAT.intf``.
The ``configinterface`` postscript can be used to pull switch interface configuration from the xCAT Management Node (MN) to the switch. Place the switch specific confguration files in the following directory on the MN: ``/install/custom/sw_os/cumulus/interface/``.
xCAT will look for files in the above directory in the following order:
1. file name that matches the switch hostname
2. file name that matches the switch group name
3. file name that has the word 'default'
Note: If the postscript cannot find a configuration file on the MN, it will set all ports on the switch to be part of VLAN 1.
Execute the script using the following command: ::
updatenode <switch> -P configinterface
@ -12,9 +24,11 @@ xCAT expects the configuration for the front-panel ports to be located at ``/etc
Re-install OS
-------------
There may be occasions where a re-install of the OS is required. Assuming the files are available on the xCAT management node, the following commands will invoke the install process:
There may be occasions where a re-install of the Cumulus Linux OS is required. The following commands can be used to invoke the install:
* **[use xCAT]** ``xdsh`` can be used to invoke the reinstall of the OS: ::
**Note:** Assumption that the Cumulus Linux files are on the xCAT MN in the correct place.
* **Using xCAT**, ``xdsh`` can invoke the reinstall of the OS: ::
# to clear out all the previous configuration, use the -k option (optional)
xdsh <switch> "/usr/cumulus/bin/onie-select -k
@ -22,7 +36,7 @@ There may be occasions where a re-install of the OS is required. Assuming the
# to invoke the reinstall of the OS
xdsh <switch> "/usr/cumulus/bin/onie-select -i -f;reboot"
* **[manually]** Log into the Cumulus OS switch and run the following commands: ::
* **Manually**, log into the switch and run the following commands: ::
sudo onie-select -i
sudo reboot

109
docs/source/advanced/networks/onie_switches/os_cumulus/upgrade.rst
View File

@ -1,62 +1,79 @@
Cumulus OS upgrade
Cumulus OS Upgrade
==================
The Cumulus OS on the ONIE switches can be upgraded in 2 ways:
The Cumulus OS on the ONIE switches can be upgraded using one of the following methods:
* Upgrade only the changed packages, using ``apt-get update`` and ``apt-get upgrade``. If the ONIE switches has internet access, this is the preferred method, otherwise, you need to build up a local cumulus mirror in the cluster.
Full Install
------------
Since in a typical cluster setup, the switches usually do not have internet access, you can create a local mirror on the server which has internet access and can be reached from the switches, the steps are ::
Perform a full install from the ``.bin`` file of the new Cumulus Linux OS version, using ONIE.
**Note:** Make sure you back up all your data and configuration files as the binary install will erase all previous configuration.
mkdir -p /install/mirror/cumulus
cd /install/mirror/cumulus
#the wget might take a long time, it will be better if you can set up
#a cron job to sync the local mirror with upstream
wget -m --no-parent http://repo3.cumulusnetworks.com/repo/
then compose a ``sources.list`` file on MN like this(take 172.21.253.37 as ip address of the local mirror server) ::
#. Place the binary image under ``/install`` on the xCAT MN node.
#cat /tmp/sources.list
deb http://172.21.253.37/install/mirror/cumulus/repo3.cumulusnetworks.com/repo CumulusLinux-3 cumulus upstream
deb-src http://172.21.253.37/install/mirror/cumulus/repo3.cumulusnetworks.com/repo CumulusLinux-3 cumulus upstream
deb http://172.21.253.37/install/mirror/cumulus/repo3.cumulusnetworks.com/repo CumulusLinux-3-security-updates cumulus upstream
deb-src http://172.21.253.37/install/mirror/cumulus/repo3.cumulusnetworks.com/repo CumulusLinux-3-security-updates cumulus upstream
deb http://172.21.253.37/install/mirror/cumulus/repo3.cumulusnetworks.com/repo CumulusLinux-3-updates cumulus upstream
deb-src http://172.21.253.37/install/mirror/cumulus/repo3.cumulusnetworks.com/repo CumulusLinux-3-updates cumulus upstream
distribute the ``sources.list`` file to the switches to upgrade with ``xdcp``, take "switch1" as an example here ::
xdcp switch1 /tmp/sources.list /etc/apt/sources.list
then invoke ``apt-get update`` and ``apt-get install`` on the switches to start package upgrade, a reboot might be needed after upgrading ::
xdsh switch1 'apt-get update && apt-get upgrade && reboot'
check the `/etc/os-release` file to make sure the Cumulus OS has been upgraded ::
cat /etc/os-release
* Performe a binary (full image) install of the new version, using ONIE. If you expect to upgrade between major versions or if you have the binary image to upgrade to, this way is the recommended one. Make sure to backup your data and configuration files because binary install will erase all the configuration and data on the switch.
The steps to perform a binary (full image) install of the new version are:
1) place the binary image "cumulus-linux-3.4.1.bin" under ``/install`` directory on MN("172.21.253.37") ::
In this example, IP=172.21.253.37 is the IP on the Management Node. ::
mkdir -p /install/onie/
cp cumulus-linux-3.4.1.bin /install/onie/
2) invoke the upgrade on switches with ``xdsh`` ::
#. Invoke the upgrade on the switches using :doc:`xdsh </guides/admin-guides/references/man1/xdsh.1>`: ::
xdsh switch1 "/usr/cumulus/bin/onie-install -a -f -i http://172.21.253.37/install/onie/cumulus-linux-3.4.1.bin && reboot"
xdsh switch1 "/usr/cumulus/bin/onie-install -a -f -i \
http://172.21.253.37/install/onie/cumulus-linux-3.4.1.bin && reboot"
The full upgrade process might cost 30 min, you can ping the switch with ``ping switch1`` to check whether it finishes upgrade.
3) After upgrading, the license should be installed, see :ref:`Activate the License <activate-the-license>` for detailed steps.
**Note:** The full upgrade process may run 30 minutes or longer.
#. After upgrading, the license should be installed, see :ref:`Activate the License <activate-the-license>` for details.
#. Restore your data and configuration files on the switch.
Update Changed Packages
-----------------------
This is the preferred method for upgrading the switch OS for incremental OS updates.
Create Local Mirror
```````````````````
If the switches do not have access to the public Internet, you can create a local mirror of the Cumulus Linux repo.
#. Create a local mirror on the Management Node: ::
4) Restore your data and configuration files on the switch.
mkdir -p /install/mirror/cumulus
cd /install/mirror/cumulus
wget -m --no-parent http://repo3.cumulusnetworks.com/repo/
#. Create a ``sources.list`` file to point to the local repo on the Management node. In this example, IP=172.21.253.37 is the IP on the Management Node. ::
# cat /tmp/sources.list
deb http://172.21.253.37/install/mirror/cumulus/repo3.cumulusnetworks.com/repo CumulusLinux-3 cumulus upstream
deb-src http://172.21.253.37/install/mirror/cumulus/repo3.cumulusnetworks.com/repo CumulusLinux-3 cumulus upstream
deb http://172.21.253.37/install/mirror/cumulus/repo3.cumulusnetworks.com/repo CumulusLinux-3-security-updates cumulus upstream
deb-src http://172.21.253.37/install/mirror/cumulus/repo3.cumulusnetworks.com/repo CumulusLinux-3-security-updates cumulus upstream
deb http://172.21.253.37/install/mirror/cumulus/repo3.cumulusnetworks.com/repo CumulusLinux-3-updates cumulus upstream
deb-src http://172.21.253.37/install/mirror/cumulus/repo3.cumulusnetworks.com/repo CumulusLinux-3-updates cumulus upstream
#. Distribute the ``sources.list`` file to your switches using :doc:`xdcp </guides/admin-guides/references/man1/xdcp.1>`. ::
xdcp switch1 /tmp/sources.list /etc/apt/sources.list
Invoke the Update
`````````````````
#. Use xCAT :doc:`xdsh </guides/admin-guides/references/man1/xdsh.1>` to invoke the update: ::
#
# A reboot may be needed after the upgrade
#
xdsh switch1 'apt-get update && apt-get upgrade && reboot'
#. Check in ``/etc/os-release`` file to verify that the OS has been upgraded.

2
docs/source/advanced/switches/ethernet_switches.rst
View File

@ -1,2 +0,0 @@
Ethernet Switches
=================

7
docs/source/advanced/switches/index.rst
View File

@ -1,7 +0,0 @@
Switch Management
=================
.. toctree::
:maxdepth: 2
ethernet_switches.rst