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
This commit is contained in:
parent
da7614bc48
commit
aa213097dc
53
README.rst
53
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
|
os-net-config
|
||||||
=============
|
=============
|
||||||
|
|
||||||
host network configuration tool
|
Team and repository tags
|
||||||
|
------------------------
|
||||||
|
|
||||||
An implementation of the 'network configuration' spec @
|
.. image:: https://governance.openstack.org/tc/badges/os-net-config.svg
|
||||||
https://review.opendev.org/#/c/97859/.
|
:target: https://governance.openstack.org/tc/reference/tags/index.html
|
||||||
The intention is for this code to be moved under the tripleo project in due course.
|
|
||||||
|
|
||||||
* 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
|
* Source: https://opendev.org/openstack/os-net-config
|
||||||
* Bugs: https://bugs.launchpad.net/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
|
Features
|
||||||
--------
|
--------
|
||||||
|
@ -104,24 +99,4 @@ YAML Config Examples
|
||||||
addresses:
|
addresses:
|
||||||
-
|
-
|
||||||
ip_netmask: 192.0.2.1/24
|
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.
|
|
||||||
|
|
||||||
|
|
|
@ -1,6 +1,79 @@
|
||||||
========
|
=====
|
||||||
Usage
|
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::
|
To use os-net-config in a project::
|
||||||
|
|
||||||
|
|
Loading…
Reference in New Issue