From aa213097dcd7c1ed3924401b8846db15c53f3a0a Mon Sep 17 00:00:00 2001 From: Steve Baker Date: Thu, 4 Feb 2021 14:30:02 +1300 Subject: [PATCH] Refresh README.rst, expand usage.rst As part of an effort to fully document os-net-config, this change makes the README.rst more consistent with other projects, and expands the usage.rst page to describe useful command-line arguments. Now that the README has a link to the generated documentation[1], the provider section can be replaced by the one in the usage.rst page. [1] https://docs.openstack.org/os-net-config/latest/ Change-Id: I065da7c7028bf081fb1d87ef64c4f3f873bfe111 --- README.rst | 53 ++++++++---------------------- doc/source/usage.rst | 77 ++++++++++++++++++++++++++++++++++++++++++-- 2 files changed, 89 insertions(+), 41 deletions(-) diff --git a/README.rst b/README.rst index 3fb1a0f0..6430ecaa 100644 --- a/README.rst +++ b/README.rst @@ -1,30 +1,25 @@ -======================== -Team and repository tags -======================== - -.. image:: https://governance.openstack.org/tc/badges/os-net-config.svg - :target: https://governance.openstack.org/tc/reference/tags/index.html - -.. Change things from this point on - ============= os-net-config ============= -host network configuration tool +Team and repository tags +------------------------ -An implementation of the 'network configuration' spec @ -https://review.opendev.org/#/c/97859/. -The intention is for this code to be moved under the tripleo project in due course. +.. image:: https://governance.openstack.org/tc/badges/os-net-config.svg + :target: https://governance.openstack.org/tc/reference/tags/index.html -* Free software: Apache License (2.0) +Overview +-------- + +``os-net-config`` is a host network configuration tool which supports multiple +backend configuration providers. + +* Documentation: https://docs.openstack.org/os-net-config/latest * Source: https://opendev.org/openstack/os-net-config * Bugs: https://bugs.launchpad.net/os-net-config +* Release Notes: https://docs.openstack.org/releasenotes/os-net-config +* Free software: Apache License (2.0) -Release Notes -------------- - -* https://docs.openstack.org/releasenotes/os-net-config Features -------- @@ -104,24 +99,4 @@ YAML Config Examples addresses: - ip_netmask: 192.0.2.1/24 - - .. - -Provider Configuration ----------------------- -Providers are use to apply (implement) the desired configuration on the -host system. By default 3 providers are implemented: - -* Ifcfg: persistent network config format stored in - /etc/sysconfig/network-scripts - -* ENI: persistent network config format stored in /etc/network/interfaces - -* iproute2: non-persistent provider which implements the config using - iproute2, vconfig, etc... (implementation in progress) - -When using bin/os-net-config the provider is automatically selected based on -the host systems perferred persistent network type (ifcfg or ENI). This can -be customized via the `--provider` CLI option. - - + \ No newline at end of file diff --git a/doc/source/usage.rst b/doc/source/usage.rst index 6585240c..852e7b88 100644 --- a/doc/source/usage.rst +++ b/doc/source/usage.rst @@ -1,6 +1,79 @@ -======== +===== Usage -======== +===== + +Backend Provider Detection +-------------------------- + +The ``--provider`` argument to ``os-net-config`` selects one of the available +backend providers: + +- ``ifcfg`` Configure network interfaces using the ifcfg format + ``/etc/sysconfig/network-scripts/`` files. +- ``eni`` Configure network interfaces using the Debian/Ubuntu + ``/etc/network/interfaces`` format +- ``iproute`` (Not implemented) + +When the ``--provider`` argument is not specified when calling +``os-net-config`` the provider will be chosen using the following rules: + +1) If path ``/etc/sysconfig/network-scripts/`` exists, use the ``ifcfg`` + provider. + +2) Otherwise if path ``/etc/network/`` exists, use the ``eni`` provider. + +In these rules, if a path is specified for ``--root-dir`` this will be +prepended to the checked paths before doing the above tests. + +Interface Mapping +----------------- + +The file ``/etc/os-net-config/mapping.yaml`` can contain mappings from +interface identifiers to the actual interface names. A different mapping file can +be used by using the ``--mapping-file`` argument to ``os-net-config``. + +This mapping allows consistent interface identifiers to be used in the config +without needing the full interface name which can vary across servers and +hardware changes. This also allows config to be performed for interfaces +which are in a ``DOWN`` state before configuration. + +The format of the mapping.yaml is as follows: + + .. code-block:: yaml + + interface_mapping: + nic1: enp0s20f0u2u1u2 + nic2: enp0s31f6 + +To assist in writing this file, the following command will generate a JSON +snippet with discovered interfaces:: + + $ os-net-config --interfaces + {'nic1': 'enp0s20f0u2u1u2', 'nic2': 'enp0s31f6'} + +When the ``--persist-mapping`` argument is specified when calling +``os-net-config`` then the existing interfaces names will be permanently +renamed to their identifier name. + +Network Configuration +--------------------- + +By default the file ``/etc/os-net-config/config.yaml`` will be sourced for +the network configuration, but an alternate file can be used with the +``--config-file`` argument. The following arguments change the behaviour +during configuration: + +- ``--detailed-exit-codes`` If enabled an exit code of ``2`` means that + files were modified. +- ``--exit-on-validation-errors`` Exit with an error if configuration + file validation fails. +- ``--noop`` Return the configuration commands, without applying them. +- ``--no-activate`` Install the configuration but don't start/stop + interfaces. +- ``--cleanup`` Cleanup unconfigured interfaces. + +Python Library +-------------- To use os-net-config in a project::