pax_global_header 0000666 0000000 0000000 00000000064 14431205264 0014513 g ustar 00root root 0000000 0000000 52 comment=5df4140c49f242cb63efcd5edffe6a06419150fb
netplan-0.106.1/ 0000775 0000000 0000000 00000000000 14431205264 0013321 5 ustar 00root root 0000000 0000000 netplan-0.106.1/.coveragerc 0000664 0000000 0000000 00000000044 14431205264 0015440 0 ustar 00root root 0000000 0000000 [run]
concurrency = multiprocessing
netplan-0.106.1/.editorconfig 0000664 0000000 0000000 00000000164 14431205264 0015777 0 ustar 00root root 0000000 0000000 root = true
[*.{c,h,py}]
indent_style = space
indent_size = 4
[*.{yml,yaml}]
indent_style = space
indent_size = 2
netplan-0.106.1/.github/ 0000775 0000000 0000000 00000000000 14431205264 0014661 5 ustar 00root root 0000000 0000000 netplan-0.106.1/.github/pull_request_template.md 0000664 0000000 0000000 00000000441 14431205264 0021621 0 ustar 00root root 0000000 0000000
## Description
## Checklist
- [ ] Runs `make check` successfully.
- [ ] Retains 100% code coverage (`make check-coverage`).
- [ ] New/changed keys in YAML format are documented.
- [ ] \(Optional\) Adds example YAML for new feature.
- [ ] \(Optional\) Closes an open bug in Launchpad.
netplan-0.106.1/.github/workflows/ 0000775 0000000 0000000 00000000000 14431205264 0016716 5 ustar 00root root 0000000 0000000 netplan-0.106.1/.github/workflows/autopkgtest.yml 0000664 0000000 0000000 00000004322 14431205264 0022014 0 ustar 00root root 0000000 0000000 name: Autopkgtest CI
# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the main branch
on:
push:
branches: [ main, 'stable/**' ]
pull_request:
branches: [ '**' ]
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
lxd-ubuntu-jammy:
# The type of runner that the job will run on
runs-on: ubuntu-22.04
# Steps represent a sequence of tasks that will be executed as part of the job
steps:
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
- uses: actions/checkout@v2
# Setup LXD + Docker fixes
- uses: canonical/setup-lxd@v0.1.1
with:
channel: latest/stable # switch from distro's LTS channel to latest/stable
- run: |
git fetch --unshallow --tags
# Install openvswitch-switch to make the OVS integration tests work
# Install linux-modules-extra-azure to provide the 'vrf' kernel module,
# it's needed (will be auto-loaded) by routing.test_vrf_basic
- name: Install dependencies
run: |
sudo sed -i '/deb-src/s/^# //' /etc/apt/sources.list
sudo apt update
sudo apt install autopkgtest ubuntu-dev-tools devscripts openvswitch-switch linux-modules-extra-$(uname -r)
# work around LP: #1878225 as fallback
- name: Preparing autopkgtest-build-lxd
run: |
sudo patch /usr/bin/autopkgtest-build-lxd .github/workflows/snapd.patch
autopkgtest-build-lxd ubuntu-daily:jammy
- name: Prepare test
run: |
pull-lp-source netplan.io
cp -r netplan.io-*/debian .
rm -r debian/patches/ # clear any distro patches
dch -v $(git describe --tags) "Autopkgtest CI testing (Jammy)"
- name: Run autopkgtest (incl. build)
run: |
# using --setup-commands temporarily to install:
# cmocka/pytest/rich/ethtool until they become proper test-deps
autopkgtest . --setup-commands='apt -y install ethtool python3-rich python3-pytest python3-pytest-cov libcmocka-dev' -U --env=DPKG_GENSYMBOLS_CHECK_LEVEL=0 --env=DEB_BUILD_OPTIONS=nocheck -- lxd autopkgtest/ubuntu/jammy/amd64
netplan-0.106.1/.github/workflows/build-abi.yml 0000664 0000000 0000000 00000003312 14431205264 0021270 0 ustar 00root root 0000000 0000000 name: Build & ABI compatibility
# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the main branch
on:
push:
branches: [ main, 'stable/**' ]
pull_request:
branches: [ main, 'stable/**' ]
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
# This workflow contains a single job called "build"
build:
# The type of runner that the job will run on
runs-on: ubuntu-22.04
# Steps represent a sequence of tasks that will be executed as part of the job
steps:
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
- uses: actions/checkout@v2
# Installs the build dependencies
# Always include phased updates (LP: #1979244)
- name: Install build depends
run: |
echo "APT::Get::Always-Include-Phased-Updates \"true\";" | sudo tee /etc/apt/apt.conf.d/90phased-updates
sudo sed -i '/deb-src/s/^# //' /etc/apt/sources.list
sudo apt update
#sudo apt install lcov python3-coverage curl
sudo apt install abigail-tools meson python3-coverage python3-pytest python3-pytest-cov
sudo apt build-dep netplan.io
# Runs the build
# TODO: move to meson build (on Jammy), once available
- name: Run build
run: |
meson setup _build -Dunit_testing=false --prefix=/usr
meson compile -C _build
# Abigail ABI checker
- name: Check ABI compatibility
run: |
abidiff abi-compat/jammy_0.106.xml _build/src/libnetplan.so.0.0 --headers-dir2 include/ --header-file2 src/abi.h --suppressions abi-compat/suppressions.abignore --no-added-syms
netplan-0.106.1/.github/workflows/check-address-sanitizer.yml 0000664 0000000 0000000 00000001703 14431205264 0024150 0 ustar 00root root 0000000 0000000 name: Check for memory issues
# This action will compile netplan with ASAN (address sanitizer) and run
# all the C unit tests and call the generator for every single file in the
# examples directory.
# The job will fail if a memory issue is detected by ASAN.
on:
push:
branches: [ main, 'stable/**' ]
pull_request:
branches: [ '**' ]
jobs:
memory-sanitizer:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v2
- name: Install build depends
run: |
echo "APT::Get::Always-Include-Phased-Updates \"true\";" | sudo tee /etc/apt/apt.conf.d/90phased-updates
sudo sed -i '/deb-src/s/^# //' /etc/apt/sources.list
sudo apt update
sudo apt -y install python3-rich python3-coverage python3-pytest python3-pytest-cov curl meson gcovr expect libcmocka-dev
sudo apt -y build-dep netplan.io
- name: Run unit tests
run: |
unbuffer ./tools/run_asan.sh
netplan-0.106.1/.github/workflows/check-coverage.yml 0000664 0000000 0000000 00000003471 14431205264 0022314 0 ustar 00root root 0000000 0000000 name: Unit tests & Coverage
# Controls when the action will run. Triggers the workflow on push or pull request
# events but only for the main branch
on:
push:
branches: [ main, 'stable/**' ]
pull_request:
branches: [ '**' ]
# A workflow run is made up of one or more jobs that can run sequentially or in parallel
jobs:
# This workflow contains a single job called "test-and-coverage"
test-and-coverage:
# The type of runner that the job will run on
runs-on: ubuntu-22.04
# Steps represent a sequence of tasks that will be executed as part of the job
steps:
# Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
- uses: actions/checkout@v2
# Installs the build dependencies, simulating a TTY/PTY via 'unbuffer' to
# to fix test_terminal.py on GA (https://github.com/actions/runner/issues/241)
# Always include phased updates (LP: #1979244)
- name: Install build depends
run: |
echo "APT::Get::Always-Include-Phased-Updates \"true\";" | sudo tee /etc/apt/apt.conf.d/90phased-updates
sudo sed -i '/deb-src/s/^# //' /etc/apt/sources.list
sudo apt update
sudo apt install python3-rich python3-coverage python3-pytest python3-pytest-cov curl meson gcovr expect libcmocka-dev
sudo apt build-dep netplan.io
# Runs the unit tests with coverage
- name: Run unit tests
run: |
meson setup _build --prefix=/usr -Db_coverage=true -Dunit_testing=true
meson compile -C _build
unbuffer meson test -C _build --verbose
# Checks the coverage diff to the main branch
#- name: Upload coverage to Codecov
# uses: codecov/codecov-action@v1
# with:
# name: check-coverage
# fail_ci_if_error: true
# verbose: true
netplan-0.106.1/.github/workflows/check-wording.yaml 0000664 0000000 0000000 00000000545 14431205264 0022332 0 ustar 00root root 0000000 0000000 name: Check for non-inclusive language
on:
push:
branches: [ main, 'stable/**' ]
pull_request:
branches: [ '**' ]
jobs:
build:
runs-on: ubuntu-22.04
steps:
- uses: actions/checkout@v3
- name: Run Woke action
uses: get-woke/woke-action@v0
with:
fail-on-error: true
woke-args: -o text
netplan-0.106.1/.github/workflows/codeql-analysis.yml 0000664 0000000 0000000 00000005206 14431205264 0022534 0 ustar 00root root 0000000 0000000 # For most projects, this workflow file will not need changing; you simply need
# to commit it to your repository.
#
# You may wish to alter this file to override the set of languages analyzed,
# or to provide custom queries or build logic.
#
# ******** NOTE ********
# We have attempted to detect the languages in your repository. Please check
# the `language` matrix defined below to confirm you have the correct set of
# supported CodeQL languages.
#
name: "CodeQL"
on:
push:
branches: [ main, 'stable/**' ]
pull_request:
# The branches below must be a subset of the branches above
branches: [ main, 'stable/**' ]
schedule:
- cron: '17 21 * * 2'
jobs:
analyze:
name: Analyze
runs-on: ubuntu-22.04
strategy:
fail-fast: false
matrix:
language: [ 'cpp', 'python' ]
# CodeQL supports [ 'cpp', 'csharp', 'go', 'java', 'javascript', 'python' ]
# Learn more:
# https://docs.github.com/en/free-pro-team@latest/github/finding-security-vulnerabilities-and-errors-in-your-code/configuring-code-scanning#changing-the-languages-that-are-analyzed
steps:
- name: Checkout repository
uses: actions/checkout@v2
# Initializes the CodeQL tools for scanning.
- name: Initialize CodeQL
uses: github/codeql-action/init@v2
with:
languages: ${{ matrix.language }}
# If you wish to specify custom queries, you can do so here or in a config file.
# By default, queries listed here will override any specified in a config file.
# Prefix the list here with "+" to use these queries and those in the config file.
# queries: ./path/to/local/query, your-org/your-repo/queries@main
# Installs the build dependencies
- name: Install build depends
run: |
sudo sed -i '/deb-src/s/^# //' /etc/apt/sources.list
sudo apt update
sudo apt install meson python3-coverage python3-pytest python3-pytest-cov libcmocka-dev
sudo apt build-dep netplan.io
# Autobuild attempts to build any compiled languages (C/C++, C#, or Java).
# If this step fails, then you should remove it and run the build manually (see below)
- name: Autobuild
uses: github/codeql-action/autobuild@v2
# ℹ️ Command-line programs to run using the OS shell.
# 📚 https://git.io/JvXDl
# ✏️ If the Autobuild fails above, remove it and uncomment the following three lines
# and modify them (or add more) to build your code if your project
# uses a compiled language
#- run: |
# make bootstrap
# make release
- name: Perform CodeQL Analysis
uses: github/codeql-action/analyze@v2
netplan-0.106.1/.github/workflows/snapd.patch 0000664 0000000 0000000 00000000447 14431205264 0021051 0 ustar 00root root 0000000 0000000 @@ -70,6 +70,8 @@
sleep 5
if lxc exec "$CONTAINER" -- systemctl mask serial-getty@getty.service; then
+ lxc exec "$CONTAINER" -- systemctl mask snapd.service
+ lxc exec "$CONTAINER" -- systemctl mask snapd.seeded.service
lxc exec "$CONTAINER" -- reboot
fi
netplan-0.106.1/.github/workflows/spread.yml 0000664 0000000 0000000 00000000705 14431205264 0020721 0 ustar 00root root 0000000 0000000 name: Run spread
on:
push:
branches: [ main, 'stable/**' ]
pull_request:
branches: [ main, 'stable/**' ]
jobs:
spread:
runs-on: ubuntu-latest
steps:
- uses: canonical/setup-lxd@v0.1.1
- uses: actions/checkout@v2
- name: Install spread
run: |
go install github.com/snapcore/spread/cmd/spread@latest
- name: Run the spread test inside LXD
run: |
~/go/bin/spread -v lxd:
netplan-0.106.1/.gitignore 0000664 0000000 0000000 00000000244 14431205264 0015311 0 ustar 00root root 0000000 0000000 generate
netplan-dbus
test-coverage
doc/*.html
doc/*.[1-9]
__pycache__
*.pyc
.coverage
.vscode
src/_features.h
netplan/_features.py
dbus/io.netplan.Netplan.service
netplan-0.106.1/.readthedocs.yaml 0000664 0000000 0000000 00000000751 14431205264 0016553 0 ustar 00root root 0000000 0000000 # .readthedocs.yaml
# Read the Docs configuration file
# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
# Required
version: 2
# Set the version of Python and environment
build:
os: ubuntu-22.04
tools:
python: "3.11"
# Build documentation in the doc/ directory with Sphinx
sphinx:
configuration: doc/conf.py
builder: dirhtml
# Declare the Python requirements required to build your docs
python:
install:
- requirements: doc/requirements.txt
netplan-0.106.1/.woke.yaml 0000664 0000000 0000000 00000006173 14431205264 0015237 0 ustar 00root root 0000000 0000000 ignore_files:
- abi-compat/*.xml
rules:
# Including some terms from https://inclusivenaming.org/ that are not in the default ruleset
- name: abort
terms:
- abort
alternatives:
- force quit
- halt
- close
- name: cripple
terms:
- cripple
alternatives:
- degraded
- restrict
- name: segregate
terms:
- segregate
- segregation
alternatives:
- segment/segmentation
- separate/separation
# From https://github.com/canonical/Inclusive-naming
# Overtly racist terms
- name: whitelist
terms:
- whitelist
- white-list
- whitelisted
- white-listed
- whitelisting
- white-listing
alternatives:
- allowlist
severity: warning
- name: blacklist
terms:
- blacklist
- black-list
- blacklisted
- black-listed
- blacklisting
- black-listing
alternatives:
- denylist
- blocklist
severity: warning
- name: blackhat
terms:
- blackhat
- black hat
alternatives:
- malicious actor
- attacker
severity: warning
- name: illegal characters
terms:
- illegal characters
alternatives:
- invalid characters
- unsupported characters
severity: warning
- name: master
terms:
- master
alternatives:
- primary
- main
severity: warning
- name: slave
terms:
- slave
alternatives:
- secondary
- replica
severity: warning
- name: whitehat
terms:
- whitehat
- white hat
alternatives:
- researcher
- security specialist
severity: warning
# Overtly Sexist/Transphobic/Homophobic/Default Male Gendered Terms/Pejorative about Gender Identity/Discriminative
- name: chairman
terms:
- chairman
- foreman
alternatives:
- chair
- foreperson
severity: warning
- name: dummy
terms:
- dummy
alternatives:
- placeholder
- sample
severity: warning
- name: grandfathered
terms:
- grandfathered
alternatives:
- legacied
severity: warning
- name: guys
terms:
- guys
alternatives:
- people
- folks
severity: warning
- name: hang
terms:
- hang
alternatives:
- stop responding
- stall
severity: warning
options:
word_boundary: true
- name: man hours
terms:
- man hours
alternatives:
- staff hours
- hours of effort
severity: warning
- name: man in the middle
terms:
- man in the middle
- man-in-the-middle
alternatives:
- machine-in-the-middle
- person-in-the-middle
severity: warning
- name: manned
terms:
- manned
alternatives:
- staffed
- monitored
severity: warning
- name: middleman
terms:
- middleman
alternatives:
- middleperson
- intermediary
severity: warning
- name: sanity check
terms:
- sanity
alternatives:
- confidence check
- coherence check
severity: warning
# Ignore rules
- name: he
netplan-0.106.1/CONTRIBUTING 0000664 0000000 0000000 00000004750 14431205264 0015161 0 ustar 00root root 0000000 0000000 # Contributing to netplan.io
Thanks for taking the time to contribute to netplan!
Here are the guidelines for contributing to the development of netplan. These
are guidelines, not hard and fast rules; but please exercise judgement. Feel
free to propose changes to this document.
#### Table Of Contents
[Code of Conduct](#code-of-conduct)
[What should I know before I get started](#what-should-i-know-before-i-get-started)
* [Did you find a bug?](#did-you-find-a-bug)
* [Code Quality](#code-quality)
* [Conventions](#conventions)
## Code of Conduct
This project and everyone participating in it is governed by the
[Ubuntu Code of Conduct](https://www.ubuntu.com/community/code-of-conduct).
By participating, you are expected to uphold this code. Please report
unacceptable behavior to
[netplan-developers@lists.launchpad.net](mailto:netplan-developers@lists.launchpad.net).
## What should I know before I get started?
### Did you find a bug?
If you've found a bug, please make sure to report it on Launchpad against the
[netplan](http://bugs.launchpad.net/netplan) project. We do use these bug reports
to make it easier to backport features to supported releases of Ubuntu: having
an existing bug report, with people who understand well how the bug appears
helps immensely in making sure the feature or bug fix is well tested when it is
being released to supported Ubuntu releases.
### Code quality
We want to maintain the quality of the code in netplan to the highest possible
degree. As such, we do insist on keeping a code coverage with unit tests to 100%
coverage if it is possible. If not, please make sure to explain why when submitting
a pull request, and expect reviewers to challenge you on that decision and suggest
a course of action.
### Conventions
The netplan project mixes C and python code. Generator code is generally all
written in C, while the UI / command-line interface is written in python. Please
look at the surrounding code, and make a best effort to follow the general style
used in the code. We do insist on proper indentation (4 spaces), but we will
not block good features and bug fixes on purely style issues. Please exercise
your best judgement: if it looks odd or too clever to you, chances are it will
look odd or too clever to code reviewers. In that case, you may be asked for
some styles changes in a pull request. Similarly, if you see code that you
find hard to understand, we do encourage that you submit pull requests that
help make the code easier to understand and maintain.
netplan-0.106.1/COPYING 0000664 0000000 0000000 00000104513 14431205264 0014360 0 ustar 00root root 0000000 0000000 GNU GENERAL PUBLIC LICENSE
Version 3, 29 June 2007
Copyright (C) 2007 Free Software Foundation, Inc.
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.
Preamble
The GNU General Public License is a free, copyleft license for
software and other kinds of works.
The licenses for most software and other practical works are designed
to take away your freedom to share and change the works. By contrast,
the GNU General Public License is intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users. We, the Free Software Foundation, use the
GNU General Public License for most of our software; it applies also to
any other work released this way by its authors. You can apply it to
your programs, too.
When we speak of free software, we are referring to freedom, not
price. Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.
To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights. Therefore, you have
certain responsibilities if you distribute copies of the software, or if
you modify it: responsibilities to respect the freedom of others.
For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received. You must make sure that they, too, receive
or can get the source code. And you must show them these terms so they
know their rights.
Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.
For the developers' and authors' protection, the GPL clearly explains
that there is no warranty for this free software. For both users' and
authors' sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.
Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the manufacturer
can do so. This is fundamentally incompatible with the aim of
protecting users' freedom to change the software. The systematic
pattern of such abuse occurs in the area of products for individuals to
use, which is precisely where it is most unacceptable. Therefore, we
have designed this version of the GPL to prohibit the practice for those
products. If such problems arise substantially in other domains, we
stand ready to extend this provision to those domains in future versions
of the GPL, as needed to protect the freedom of users.
Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish to
avoid the special danger that patents applied to a free program could
make it effectively proprietary. To prevent this, the GPL assures that
patents cannot be used to render the program non-free.
The precise terms and conditions for copying, distribution and
modification follow.
TERMS AND CONDITIONS
0. Definitions.
"This License" refers to version 3 of the GNU General Public License.
"Copyright" also means copyright-like laws that apply to other kinds of
works, such as semiconductor masks.
"The Program" refers to any copyrightable work licensed under this
License. Each licensee is addressed as "you". "Licensees" and
"recipients" may be individuals or organizations.
To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy. The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.
A "covered work" means either the unmodified Program or a work based
on the Program.
To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy. Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.
To "convey" a work means any kind of propagation that enables other
parties to make or receive copies. Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.
An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License. If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.
1. Source Code.
The "source code" for a work means the preferred form of the work
for making modifications to it. "Object code" means any non-source
form of a work.
A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.
The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form. A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.
The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities. However, it does not include the work's
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work. For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.
The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.
The Corresponding Source for a work in source code form is that
same work.
2. Basic Permissions.
All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met. This License explicitly affirms your unlimited
permission to run the unmodified Program. The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work. This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.
You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force. You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright. Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.
Conveying under any other circumstances is permitted solely under
the conditions stated below. Sublicensing is not allowed; section 10
makes it unnecessary.
3. Protecting Users' Legal Rights From Anti-Circumvention Law.
No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.
When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work's
users, your or third parties' legal rights to forbid circumvention of
technological measures.
4. Conveying Verbatim Copies.
You may convey verbatim copies of the Program's source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.
You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.
5. Conveying Modified Source Versions.
You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:
a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.
b) The work must carry prominent notices stating that it is
released under this License and any conditions added under section
7. This requirement modifies the requirement in section 4 to
"keep intact all notices".
c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy. This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged. This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.
d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.
A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation's users
beyond what the individual works permit. Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.
6. Conveying Non-Source Forms.
You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
machine-readable Corresponding Source under the terms of this License,
in one of these ways:
a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.
b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.
c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source. This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.
d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge. You need not require recipients to copy the
Corresponding Source along with the object code. If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source. Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.
e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.
A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.
A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling. In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage. For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product. A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.
"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source. The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because
modification has been made.
If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information. But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).
The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed. Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.
Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for
unpacking, reading or copying.
7. Additional Terms.
"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law. If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by
this License without regard to the additional permissions.
When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it. (Additional permissions may be written to require their own
removal in certain cases when you modify the work.) You may place
additional permissions on material, added by you to a covered work,
for which you have or can give appropriate copyright permission.
Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:
a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or
b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or
c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or
d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or
e) Declining to grant rights under trademark law for use of some
trade names, trademarks, or service marks; or
f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.
All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10. If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term. If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.
If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.
Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.
8. Termination.
You may not propagate or modify a covered work except as expressly
provided under this License. Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
this License (including any patent licenses granted under the third
paragraph of section 11).
However, if you cease all violation of this License, then your
license from a particular copyright holder is reinstated (a)
provisionally, unless and until the copyright holder explicitly and
finally terminates your license, and (b) permanently, if the copyright
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.
Moreover, your license from a particular copyright holder is
reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.
Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License. If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.
9. Acceptance Not Required for Having Copies.
You are not required to accept this License in order to receive or
run a copy of the Program. Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance. However,
nothing other than this License grants you permission to propagate or
modify any covered work. These actions infringe copyright if you do
not accept this License. Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.
10. Automatic Licensing of Downstream Recipients.
Each time you convey a covered work, the recipient automatically
receives a license from the original licensors, to run, modify and
propagate that work, subject to this License. You are not responsible
for enforcing compliance by third parties with this License.
An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations. If propagation of a covered
work results from an entity transaction, each party to that
transaction who receives a copy of the work also receives whatever
licenses to the work the party's predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.
You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License. For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.
11. Patents.
A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based. The
work thus licensed is called the contributor's "contributor version".
A contributor's "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version. For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of
this License.
Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor's essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.
In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement). To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.
If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients. "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient's use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.
If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.
A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License. You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.
Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.
12. No Surrender of Others' Freedom.
If conditions are imposed on you (whether by court order, agreement or
otherwise) that contradict the conditions of this License, they do not
excuse you from the conditions of this License. If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all. For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.
13. Use with the GNU Affero General Public License.
Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work. The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.
14. Revised Versions of this License.
The Free Software Foundation may publish revised and/or new versions of
the GNU General Public License from time to time. Such new versions will
be similar in spirit to the present version, but may differ in detail to
address new problems or concerns.
Each version is given a distinguishing version number. If the
Program specifies that a certain numbered version of the GNU General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation. If the Program does not specify a version number of the
GNU General Public License, you may choose any version ever published
by the Free Software Foundation.
If the Program specifies that a proxy can decide which future
versions of the GNU General Public License can be used, that proxy's
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.
Later license versions may give you additional or different
permissions. However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.
15. Disclaimer of Warranty.
THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU. SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.
16. Limitation of Liability.
IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.
17. Interpretation of Sections 15 and 16.
If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.
END OF TERMS AND CONDITIONS
How to Apply These Terms to Your New Programs
If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.
To do so, attach the following notices to the program. It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.
Copyright (C)
This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
GNU General Public License for more details.
You should have received a copy of the GNU General Public License
along with this program. If not, see .
Also add information on how to contact you by electronic and paper mail.
If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:
Copyright (C)
This program comes with ABSOLUTELY NO WARRANTY; for details type `show w'.
This is free software, and you are welcome to redistribute it
under certain conditions; type `show c' for details.
The hypothetical commands `show w' and `show c' should show the appropriate
parts of the General Public License. Of course, your program's commands
might be different; for a GUI interface, you would use an "about box".
You should also get your employer (if you work as a programmer) or school,
if any, to sign a "copyright disclaimer" for the program, if necessary.
For more information on this, and how to apply and follow the GNU GPL, see
.
The GNU General Public License does not permit incorporating your program
into proprietary programs. If your program is a subroutine library, you
may consider it more useful to permit linking proprietary applications with
the library. If this is what you want to do, use the GNU Lesser General
Public License instead of this License. But first, please read
.
netplan-0.106.1/Makefile 0000664 0000000 0000000 00000015752 14431205264 0014773 0 ustar 00root root 0000000 0000000 NETPLAN_SOVER=0.0
BUILDFLAGS = \
-g \
-fPIC \
-std=c99 \
-D_GNU_SOURCE \
-DSBINDIR=\"$(SBINDIR)\" \
-I${CURDIR}/include \
-Wall \
-Werror \
$(NULL)
TESTFLAGS = \
-g \
-O0 \
-DFIXTURESDIR=\"$(shell pwd)/tests/ctests/fixtures\" \
-Isrc \
--coverage \
-lcmocka \
$(NULL)
SRCS = \
src/abi_compat.c \
src/error.c \
src/names.c \
src/netplan.c \
src/networkd.c \
src/nm.c \
src/openvswitch.c \
src/parse.c \
src/parse-nm.c \
src/sriov.c \
src/types.c \
src/util.c \
src/validation.c \
$(NULL)
TESTS = \
tests/ctests/test_netplan_error \
tests/ctests/test_netplan_misc \
tests/ctests/test_netplan_parser \
tests/ctests/test_netplan_state \
$(NULL)
SYSTEMD_GENERATOR_DIR=$(shell pkg-config --variable=systemdsystemgeneratordir systemd)
SYSTEMD_UNIT_DIR=$(shell pkg-config --variable=systemdsystemunitdir systemd)
BASH_COMPLETIONS_DIR=$(shell pkg-config --variable=completionsdir bash-completion || echo "/etc/bash_completion.d")
GCOV ?= gcov
ROOTPREFIX ?=
PREFIX ?= /usr
LIBDIR ?= $(PREFIX)/lib
ROOTLIBEXECDIR ?= $(ROOTPREFIX)/lib
LIBEXECDIR ?= $(PREFIX)/lib
SBINDIR ?= $(PREFIX)/sbin
DATADIR ?= $(PREFIX)/share
DOCDIR ?= $(DATADIR)/doc
MANDIR ?= $(DATADIR)/man
INCLUDEDIR ?= $(PREFIX)/include
PYCODE = netplan/ $(wildcard src/*.py) $(wildcard tests/*.py) $(wildcard tests/generator/*.py) $(wildcard tests/cli/*.py) $(wildcard tests/netplan_dbus/*.py) $(wildcard tests/integration/*.py) $(wildcard tests/parser/*.py)
# Order: Fedora/Mageia/openSUSE || Debian/Ubuntu || null
PYFLAKES3 ?= $(shell command -v pyflakes-3 || command -v pyflakes3 || echo true)
PYCODESTYLE3 ?= $(shell command -v pycodestyle-3 || command -v pycodestyle || command -v pep8 || echo true)
PYTEST3 ?= $(shell command -v pytest-3 || command -v pytest3 || echo true)
PYCOVERAGE ?= $(shell command -v python3-coverage || echo true)
default: netplan/_features.py generate netplan-dbus dbus/io.netplan.Netplan.service doc/netplan.html doc/netplan.5 doc/netplan-generate.8 doc/netplan-apply.8 doc/netplan-try.8 doc/netplan-dbus.8 doc/netplan-get.8 doc/netplan-set.8
%.o: src/%.c src/_features.h
$(CC) $(BUILDFLAGS) $(CFLAGS) $(LDFLAGS) -c $^ `pkg-config --cflags --libs glib-2.0 gio-2.0 yaml-0.1 uuid`
libnetplan.so.$(NETPLAN_SOVER): $(SRCS) abicompat.lds
$(CC) -shared -Wl,-soname,libnetplan.so.$(NETPLAN_SOVER) $(BUILDFLAGS) $(CFLAGS) -fvisibility=hidden $(LDFLAGS) -o $@ $(SRCS) -T abicompat.lds `pkg-config --cflags --libs glib-2.0 gio-2.0 yaml-0.1 uuid`
ln -snf libnetplan.so.$(NETPLAN_SOVER) libnetplan.so
generate: libnetplan.so.$(NETPLAN_SOVER) generate.o
$(CC) $(BUILDFLAGS) $(CFLAGS) $(LDFLAGS) -o $@ $(filter-out $<,$^) -L. -lnetplan `pkg-config --cflags --libs glib-2.0 gio-2.0 yaml-0.1 uuid`
netplan-dbus: libnetplan.so.$(NETPLAN_SOVER) dbus.o
$(CC) $(BUILDFLAGS) $(CFLAGS) $(LDFLAGS) -o $@ $(filter-out $<,$(patsubst %.h,,$^)) -L. -lnetplan `pkg-config --cflags --libs libsystemd glib-2.0 gio-2.0 yaml-0.1 uuid`
src/_features.h: src/[^_]*.[hc]
printf "#include \nstatic const char *feature_flags[] __attribute__((__unused__)) = {\n" > $@
awk 'match ($$0, /netplan-feature:.*/ ) { $$0=substr($$0, RSTART, RLENGTH); print "\""$$2"\"," }' $^ >> $@
echo "NULL, };" >> $@
netplan/_features.py: src/[^_]*.[hc]
echo "# Generated file" > $@
echo "NETPLAN_FEATURE_FLAGS = [" >> $@
awk 'match ($$0, /netplan-feature:.*/ ) { $$0=substr($$0, RSTART, RLENGTH); print " \""$$2"\"," }' $^ >> $@
echo "]" >> $@
$(TESTS): %: %.c
$(CC) $(BUILDFLAGS) $(CFLAGS) -o $@ $< `pkg-config --cflags --libs glib-2.0 gio-2.0 yaml-0.1 uuid` $(TESTFLAGS)
./$@
clean:
rm -f netplan/_features.py src/_features.h src/_features.h.gch
rm -f generate doc/*.html doc/*.[1-9]
rm -f *.o *.so*
rm -f netplan-dbus dbus/*.service
rm -f *.gcda *.gcno generate.info
rm -f tests/ctests/*.gcda tests/ctests/*.gcno
rm -rf test-coverage .coverage
rm -f .coverage.* coverage.xml
find . | grep -E "(__pycache__|\.pyc)" | xargs rm -rf
rm -f $(TESTS)
check: default linting $(TESTS)
PYTHONPATH=. LD_LIBRARY_PATH=. tests/cli_legacy.py
PYTHONPATH=. LD_LIBRARY_PATH=. $(PYCOVERAGE) run -a -m pytest -s -v --cov-append
tests/validate_docs.sh
linting:
$(PYFLAKES3) $(PYCODE)
$(PYCODESTYLE3) --max-line-length=130 $(PYCODE)
coverage: | pre-coverage c-coverage python-coverage-combine python-coverage
pre-coverage:
rm -f .coverage
$(MAKE) CFLAGS="-g -O0 --coverage" clean check
mkdir -p test-coverage/C test-coverage/python
check-coverage: coverage
@if grep headerCovTableEntryHi test-coverage/C/index.html | grep -qv '100.*%'; then \
echo "FAIL: Test coverage not 100%!" >&2; exit 1; \
fi
python3-coverage report --omit=/usr* --show-missing --fail-under=100
c-coverage:
lcov --directory . --capture --gcov-tool=$(GCOV) -o generate.info
lcov --remove generate.info "/usr*" -o generate.info
genhtml -o test-coverage/C/ -t "generate test coverage" generate.info
python-coverage-combine:
python3-coverage combine -a
python-coverage:
python3-coverage html -d test-coverage/python --omit=/usr* || true
python3-coverage xml --omit=/usr* || true
install: default
mkdir -p $(DESTDIR)/$(SBINDIR) $(DESTDIR)/$(ROOTLIBEXECDIR)/netplan $(DESTDIR)/$(SYSTEMD_GENERATOR_DIR) $(DESTDIR)/$(LIBDIR)
mkdir -p $(DESTDIR)/$(MANDIR)/man5 $(DESTDIR)/$(MANDIR)/man8
mkdir -p $(DESTDIR)/$(DOCDIR)/netplan/examples
mkdir -p $(DESTDIR)/$(DATADIR)/netplan/netplan
mkdir -p $(DESTDIR)/$(INCLUDEDIR)/netplan
install -m 755 generate $(DESTDIR)/$(ROOTLIBEXECDIR)/netplan/
find netplan/ -name '*.py' -exec install -Dm 644 "{}" "$(DESTDIR)/$(DATADIR)/netplan/{}" \;
install -m 755 src/netplan.script $(DESTDIR)/$(DATADIR)/netplan/
ln -srf $(DESTDIR)/$(DATADIR)/netplan/netplan.script $(DESTDIR)/$(SBINDIR)/netplan
ln -srf $(DESTDIR)/$(ROOTLIBEXECDIR)/netplan/generate $(DESTDIR)/$(SYSTEMD_GENERATOR_DIR)/netplan
# lib
install -m 644 *.so.* $(DESTDIR)/$(LIBDIR)/
ln -snf libnetplan.so.$(NETPLAN_SOVER) $(DESTDIR)/$(LIBDIR)/libnetplan.so
# headers, dev data
install -m 644 include/*.h $(DESTDIR)/$(INCLUDEDIR)/netplan/
# TODO: install pkg-config once available
# docs, data
install -m 644 doc/*.html $(DESTDIR)/$(DOCDIR)/netplan/
install -m 644 examples/*.yaml $(DESTDIR)/$(DOCDIR)/netplan/examples/
install -m 644 doc/*.5 $(DESTDIR)/$(MANDIR)/man5/
install -m 644 doc/*.8 $(DESTDIR)/$(MANDIR)/man8/
install -T -D -m 644 netplan.completions $(DESTDIR)/$(BASH_COMPLETIONS_DIR)/netplan
# dbus
mkdir -p $(DESTDIR)/$(DATADIR)/dbus-1/system.d $(DESTDIR)/$(DATADIR)/dbus-1/system-services
install -m 755 netplan-dbus $(DESTDIR)/$(ROOTLIBEXECDIR)/netplan/
install -m 644 dbus/io.netplan.Netplan.conf $(DESTDIR)/$(DATADIR)/dbus-1/system.d/
install -m 644 dbus/io.netplan.Netplan.service $(DESTDIR)/$(DATADIR)/dbus-1/system-services/
%.service: %.service.in
sed -e "s#@ROOTLIBEXECDIR@#$(ROOTLIBEXECDIR)#" $< > $@
%.html: %.md
pandoc -s --metadata title="Netplan reference" --toc -o $@ $<
doc/netplan.5: doc/manpage-header.md doc/structure-id.md doc/netplan-yaml.md doc/manpage-footer.md
pandoc -s -o $@ --from=markdown-smart $^
%.8: %.md
pandoc -s -o $@ --shift-heading-level-by=-1 --from=markdown-smart $^
.PHONY: clean
netplan-0.106.1/README.md 0000664 0000000 0000000 00000003252 14431205264 0014602 0 ustar 00root root 0000000 0000000 # netplan - Backend-agnostic network configuration in YAML
[](https://github.com/canonical/netplan/actions/workflows/build-abi.yml?query=branch%3Amain)
[](https://github.com/canonical/netplan/actions/workflows/check-coverage.yml?query=branch%3Amain)
[](https://github.com/canonical/netplan/actions/workflows/autopkgtest.yml?query=branch%3Amain)
# Website
http://netplan.io
# Documentation
An overview of the architecture can be found at [netplan.io/design](https://netplan.io/design)
The full documentation for netplan is available in the [doc/](../main/doc/) directory.
Netplan's [documentation objectives](https://docs.google.com/document/d/1n47hwLmR6GiLJX0t5w2_uGngQ3b3jfpPN8H8knIJ9vQ) (internal)
# Build using Meson
Steps to build netplan using the [Meson](https://mesonbuild.com) build system inside the `build/` directory:
* meson setup build --prefix=/usr [-Db_coverage=true]
* meson compile -C build
* meson test -C build --verbose [TEST_NAME]
* meson install -C build --destdir ../tmproot
# Bug reports
Please file bug reports in [Launchpad](https://bugs.launchpad.net/netplan/+filebug).
# Contact us
Please join us on IRC in #netplan at [Libera.Chat](https://libera.chat/).
Our mailing list is [here](https://lists.launchpad.net/netplan-developers/).
Email the list at [netplan-developers@lists.launchpad.net](mailto:netplan-developers@lists.launchpad.net).
netplan-0.106.1/TODO 0000664 0000000 0000000 00000002526 14431205264 0014016 0 ustar 00root root 0000000 0000000 - improve IPv6 RA handling
- support tunnel device types
- support ethtool/sysctl knobs (TSO, LRO, txqueuelen)
- inspecting current network config via "netplan show $interface" for a
collated view of each interface's yaml.
- debugging config generation via "netplan diff [backend|system]":
- netplan diff system: compare generated config with current ip addr output
- netplan diff backend: compare generated config with current config for backend
- support other devices types from networkd/NetworkManager:
- infiniband
- veth
- better handle VLAN Q-in-Q (mostly generation tweaks + patching backends)
- support device aliases (eth0 + eth0.1; add eth0 to multiple bridges)
- workaround for two bridges is to use eth0 and vlan1
- make errors translatable
- "netplan save" to capture kernel state into netplan YAML.
- better parsing/validation for time-based values (ie. bond, bridge params)
- openvswitch integration
- wpa enterprise support
- better parsing/validation for all schema
- improve exit codes / behavior on error
- integrate 'netplan try' in tmux/screen
- add automated integration tests for WPA Enterprise / 802.1x that can run self-contained
# After soname bump (ABI break)
- get rid of abi_compat.c
- change route->scope to ENUM
- move tunnel_ttl into tunnel struct
- store match.driver as a list rather than a string
netplan-0.106.1/abi-compat/ 0000775 0000000 0000000 00000000000 14431205264 0015335 5 ustar 00root root 0000000 0000000 netplan-0.106.1/abi-compat/README.md 0000664 0000000 0000000 00000001311 14431205264 0016610 0 ustar 00root root 0000000 0000000 # Netplan's ABI checker
We're using "abigail" (abigail-tools) to validate libnetplan's ABI.
## HowTo create a ABI reference
The `abidw` tool can be used to generate an ABI XML like this:
```
meson setup build --prefix=/usr
meson compile -C build
abidw build/src/libnetplan.so.0.0 --headers-dir include/ --header-file src/abi.h > abi-compat/jammy_0.106.xml
```
## HowTo compare a ABI
The `abidiff` tool can be used to compare a new library ABI to an existing XML
reference like this (also, see .github/workflows/build-abi.yml):
```
abidiff abi-compat/jammy_0.106.xml build/src/libnetplan.so.0.0 --headers-dir2 include/ --header-file2 src/abi.h --suppressions abi-compat/suppressions.abignore --no-added-syms
```
netplan-0.106.1/abi-compat/jammy_0.106.xml 0000664 0000000 0000000 00001253463 14431205264 0017736 0 ustar 00root root 0000000 0000000
netplan-0.106.1/abi-compat/suppressions.abignore 0000664 0000000 0000000 00000000516 14431205264 0021624 0 ustar 00root root 0000000 0000000 # Ignore this type/file/function/variable during ABI checks
# passed to abidiff using the --suppressions parameter
#
# Documentation about the syntax can be found here:
# https://sourceware.org/libabigail/manual/libabigail-concepts.html#suppression-specifications
[suppress_variable]
name = global_state
type_name = NetplanState
netplan-0.106.1/abicompat.lds 0000664 0000000 0000000 00000000517 14431205264 0015767 0 ustar 00root root 0000000 0000000 SECTIONS
{
.data.abi_compat : {
netdefs = global_state + SIZEOF(netdefs_offset) - 8;
netdefs_ordered = global_state + SIZEOF(netdefs_ordered_offset) - 8;
ovs_settings_global = global_state + SIZEOF(ovs_settings_offset) - 8;
global_backend = global_state + SIZEOF(global_backend_offset) - 8;
}
}
INSERT AFTER .data;
netplan-0.106.1/dbus/ 0000775 0000000 0000000 00000000000 14431205264 0014256 5 ustar 00root root 0000000 0000000 netplan-0.106.1/dbus/io.netplan.Netplan.conf 0000664 0000000 0000000 00000001137 14431205264 0020576 0 ustar 00root root 0000000 0000000
netplan-0.106.1/dbus/io.netplan.Netplan.service.in 0000664 0000000 0000000 00000000175 14431205264 0021717 0 ustar 00root root 0000000 0000000 [D-BUS Service]
Name=io.netplan.Netplan
Exec=@ROOTLIBEXECDIR@/netplan/netplan-dbus
User=root
AssumedAppArmorLabel=unconfined
netplan-0.106.1/dbus/meson.build 0000664 0000000 0000000 00000001735 14431205264 0016426 0 ustar 00root root 0000000 0000000 features_h = custom_target(
build_always_stale: true,
output: '_features.h',
input: join_paths(meson.project_source_root(), 'features_h_generator.sh'),
command: ['sh', '-c', '@INPUT@'],
install: false,
capture: true,
)
executable(
'netplan-dbus',
'../src/dbus.c',
features_h,
include_directories: inc,
link_with: libnetplan,
dependencies: [libsystemd, glib, gio, yaml, uuid],
install_dir: join_paths(get_option('libexecdir'), 'netplan'),
install: true)
install_data(
'io.netplan.Netplan.conf',
install_dir: join_paths(get_option('datadir'), 'dbus-1', 'system.d'))
conf_data = configuration_data()
conf_data.set('ROOTLIBEXECDIR', join_paths(get_option('prefix'), get_option('libexecdir')))
configure_file(
input: 'io.netplan.Netplan.service.in',
output: 'io.netplan.Netplan.service',
configuration: conf_data,
install: true,
install_dir: join_paths(get_option('datadir'), 'dbus-1', 'system-services'))
netplan-0.106.1/doc/ 0000775 0000000 0000000 00000000000 14431205264 0014066 5 ustar 00root root 0000000 0000000 netplan-0.106.1/doc/.gitignore 0000664 0000000 0000000 00000000017 14431205264 0016054 0 ustar 00root root 0000000 0000000 _build
/*env*/
netplan-0.106.1/doc/CODE_OF_CONDUCT.md 0000664 0000000 0000000 00000020355 14431205264 0016672 0 ustar 00root root 0000000 0000000 # Ubuntu Code of Conduct v2.0
Ubuntu is about showing humanity to one another: the word itself captures the spirit of being human.
We want a productive, happy and agile community that can welcome new ideas in a complex field, improve every process every year, and foster collaboration between groups with very different needs, interests and skills.
We gain strength from diversity, and actively seek participation from those who enhance it. This code of conduct exists to ensure that diverse groups collaborate to mutual advantage and enjoyment. We will challenge prejudice that could jeopardise the participation of any person in the project.
The Code of Conduct governs how we behave in public or in private whenever the project will be judged by our actions. We expect it to be honoured by everyone who represents the project officially or informally, claims affiliation with the project, or participates directly.
## We strive to:
* Be considerate
Our work will be used by other people, and we in turn will depend on the work of others. Any decision we take will affect users and colleagues, and we should consider them when making decisions.
* Be respectful
Disagreement is no excuse for poor manners. We work together to resolve conflict, assume good intentions and do our best to act in an empathic fashion. We don’t allow frustration to turn into a personal attack. A community where people feel uncomfortable or threatened is not a productive one.
* Take responsibility for our words and our actions
We can all make mistakes; when we do, we take responsibility for them. If someone has been harmed or offended, we listen carefully and respectfully, and work to right the wrong.
* Be collaborative
What we produce is a complex whole made of many parts, it is the sum of many dreams. Collaboration between teams that each have their own goal and vision is essential; for the whole to be more than the sum of its parts, each part must make an effort to understand the whole.Collaboration reduces redundancy and improves the quality of our work. Internally and externally, we celebrate good collaboration. Wherever possible, we work closely with upstream projects and others in the free software community to coordinate our efforts. We prefer to work transparently and involve interested parties as early as possible.
* Value decisiveness, clarity and consensus
Disagreements, social and technical, are normal, but we do not allow them to persist and fester leaving others uncertain of the agreed direction.We expect participants in the project to resolve disagreements constructively. When they cannot, we escalate the matter to structures with designated leaders to arbitrate and provide clarity and direction.
* Ask for help when unsure
Nobody is expected to be perfect in this community. Asking questions early avoids many problems later, so questions are encouraged, though they may be directed to the appropriate forum. Those who are asked should be responsive and helpful.
* Step down considerately
When somebody leaves or disengages from the project, we ask that they do so in a way that minimises disruption to the project. They should tell people they are leaving and take the proper steps to ensure that others can pick up where they left off.
## Leadership, authority and responsibility
We all lead by example, in debate and in action. We encourage new participants to feel empowered to lead, to take action, and to experiment when they feel innovation could improve the project. Leadership can be exercised by anyone simply by taking action, there is no need to wait for recognition when the opportunity to lead presents itself.
### Delegation from the top
Responsibility for the project starts with the “benevolent dictator”, who delegates specific responsibilities and the corresponding authority to a series of teams, councils and individuals, starting with the Community Council (“CC”). That Council or its delegated representative will arbitrate in any dispute.
We are a meritocracy; we delegate decision making, governance and leadership from senior bodies to the most able and engaged candidates.
### Support for delegation is measured
Nominations to the boards and councils are at the discretion of the Community Council, however the Community Council will seek the input of the community before confirming appointments.
Leadership is not an award, right, or title; it is a privilege, a responsibility and a mandate. A leader will only retain their authority as long as they retain the support of those who delegated that authority to them.
### We value discussion, data and decisiveness
We gather opinions, data and commitments from concerned parties before taking a decision. We expect leaders to help teams come to a decision in a reasonable time, to seek guidance or be willing to take the decision themselves when consensus is lacking, and to take responsibility for implementation.
The poorest decision of all is no decision: clarity of direction has value in itself. Sometimes all the data are not available, or consensus is elusive. A decision must still be made. There is no guarantee of a perfect decision every time - we prefer to err, learn, and err less in future than to postpone action indefinitely.
We recognise that the project works better when we trust the teams closest to a problem to make the decision for the project. If we learn of a decision that we disagree with, we can engage the relevant team to find common ground, and failing that, we have a governance structure that can review the decision. Ultimately, if a decision has been taken by the people responsible for it, and is supported by the project governance, it will stand. None of us expects to agree with every decision, and we value highly the willingness to stand by the project and help it deliver even on the occasions when we ourselves may prefer a different route.
### Open meritocracy
We invite anybody, from any company, to participate in any aspect of the project. Our community is open, and any responsibility can be carried by any contributor who demonstrates the required capacity and competence.
### Teamwork
A leader’s foremost goal is the success of the team.
“A virtuoso is judged by their actions; a leader is judged by the actions of their team.” A leader knows when to act and when to step back. They know when to delegate work, and when to take it upon themselves.
### Credit
A good leader does not seek the limelight, but celebrates team members for the work they do. Leaders may be more visible than members of the team, good ones use that visibility to highlight the great work of others.
### Courage and considerateness
Leadership occasionally requires bold decisions that will not be widely understood, consensual or popular. We value the courage to take such decisions, because they enable the project as a whole to move forward faster than we could if we required complete consensus. Nevertheless, boldness demands considerateness; take bold decisions, but do so mindful of the challenges they present for others, and work to soften the impact of those decisions on them. Communicating changes and their reasoning clearly and early on is as important as the implementation of the change itself.
### Conflicts of interest
We expect leaders to be aware when they are conflicted due to employment or other projects they are involved in, and abstain or delegate decisions that may be seen to be self-interested. We expect that everyone who participates in the project does so with the goal of making life better for its users.
When in doubt, ask for a second opinion. Perceived conflicts of interest are important to address; as a leader, act to ensure that decisions are credible even if they must occasionally be unpopular, difficult or favourable to the interests of one group over another.
This Code is not exhaustive or complete. It is not a rulebook; it serves to distil our common understanding of a collaborative, shared environment and goals. We expect it to be followed in spirit as much as in the letter.
*The Ubuntu Code of Conduct is licensed under the [Creative Commons Attribution-Share Alike 3.0 license](https://creativecommons.org/licenses/by-sa/3.0/). You may re-use it for your own project, and modify it as you wish, just please allow others to use your modifications and give credit to the Ubuntu Project!*
netplan-0.106.1/doc/Makefile 0000664 0000000 0000000 00000003744 14431205264 0015536 0 ustar 00root root 0000000 0000000 # Minimal makefile for Sphinx documentation
# This is for development purposes only, e.g. to run a local Sphinx
# development environment. Usage:
#
# Setup: Run `make install` from doc/ to setup a Python virtual env
# Devel: Run `make run` from doc/ to get a live preview of your changes
# Test: Run `make spelling` from doc/ to validate your spelling
#
# You can set these variables from the command line, and also
# from the environment for the first two.
SPHINXOPTS ?=
SPHINXBUILD ?= sphinx-build
SOURCEDIR = .
BUILDDIR = _build
VENV = env/bin/activate
PORT = 8090
# Put it first so that "make" without argument is like "make help".
help:
@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
install:
@echo "... setting up virtualenv"
python3 -m venv env
. $(VENV); pip install --upgrade -r requirements.txt
@echo "\n" \
"--------------------------------------------------------------- \n" \
"* watch, build and serve the documentation: make run \n" \
"* check spelling: make spelling \n" \
"\n" \
"enchant must be installed in order for pyenchant (and therefore \n" \
"spelling checks) to work. \n" \
"--------------------------------------------------------------- \n"
clean:
-rm -rf _build/*
run:
. $(VENV); sphinx-autobuild $(ALLSPHINXOPTS) --ignore ".git/*" --ignore "*.scss" . -b dirhtml -a _build/html --host 0.0.0.0 --port $(PORT)
test:
. $(VENV); $(SPHINXBUILD) -b html . _build/html
html:
. $(VENV); $(SPHINXBUILD) -b dirhtml . _build/html
spelling:
. $(VENV); $(SPHINXBUILD) -b spelling $(ALLSPHINXOPTS) . _build/spelling
@echo
@echo "Check finished. Wrong words can be found in " \
"_build/spelling/output.txt."
quickstart:
. $(VENV); sphinx-quickstart
.PHONY: help install clean run Makefile
# Catch-all target: route all unknown targets to Sphinx using the new
# "make mode" option. $(O) is meant as a shortcut for $(SPHINXOPTS).
%: Makefile
@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
netplan-0.106.1/doc/README.md 0000777 0000000 0000000 00000000000 14431205264 0016771 2index.md ustar 00root root 0000000 0000000 netplan-0.106.1/doc/cli.md 0000664 0000000 0000000 00000002435 14431205264 0015163 0 ustar 00root root 0000000 0000000 # Netplan CLI
```{toctree}
---
maxdepth: 1
hidden: true
---
generate
apply
try
get
set
info
ip
rebind
status
```
Netplan provides a command line interface, called `netplan`, which a user can
utilize to control certain aspects of the Netplan configuration.
| Tool | Description |
| --- | --- |
| help | Show a generic help message |
| [generate](/netplan-generate) | Generate backend specific configuration files from `/etc/netplan/*.yaml` |
| [apply](/netplan-apply) | Apply current netplan config to running system |
| [try](/netplan-try) | Try to apply a new netplan config to running system, with automatic rollback |
| [get](/netplan-get) | Get a setting by specifying a nested key like `"ethernets.eth0.addresses"`, or "all" |
| [set](/netplan-set) | Add new setting by specifying a dotted `key=value` pair like `"ethernets.eth0.dhcp4=true"` |
| [info](/netplan-info) | Show available features |
| [ip](/netplan-ip) | Retrieve IP information (like DHCP leases) from the system |
| [rebind](/netplan-rebind) | Rebind SR-IOV virtual functions of given physical functions to their driver |
| [status](/netplan-status) | Query networking state of the running system |
netplan-0.106.1/doc/conf.py 0000664 0000000 0000000 00000004142 14431205264 0015366 0 ustar 00root root 0000000 0000000 # Configuration file for the Sphinx documentation builder.
#
# This file only contains a selection of the most common options. For a full
# list see the documentation:
# https://www.sphinx-doc.org/en/master/usage/configuration.html wokeignore:rule=master
# -- Path setup --------------------------------------------------------------
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
#
# import os
# import sys
# sys.path.insert(0, os.path.abspath('.'))
# -- Project information -----------------------------------------------------
project = 'Netplan'
copyright = '2022, Netplan team'
author = 'Netplan team'
# -- General configuration ---------------------------------------------------
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = ['sphinx_design', 'myst_parser', 'sphinx_copybutton']
myst_enable_extensions = ["colon_fence"]
smartquotes_action = 'qe'
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
# This pattern also affects html_static_path and html_extra_path.
exclude_patterns = ['_build', 'Thumbs.db', '.DS_Store', 'env']
# -- Options for HTML output -------------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
#
html_theme = 'furo'
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# The logo
html_logo = 'netplan.svg'
# -- Options for MyST --------------------------------------------------------
myst_title_to_header = True
netplan-0.106.1/doc/dbus-config.md 0000664 0000000 0000000 00000004536 14431205264 0016620 0 ustar 00root root 0000000 0000000 # Use D-Bus config API
See also:
* [Netplan D-Bus reference](/netplan-dbus)
* [busctl reference](https://www.freedesktop.org/software/systemd/man/busctl.html)
Copy the current state from `/{etc,run,lib}/netplan/*.yaml` by creating a new config object
```
$ busctl call io.netplan.Netplan /io/netplan/Netplan io.netplan.Netplan Config
o "/io/netplan/Netplan/config/ULJIU0"
```
Read the merged YAML configuration
```
$ busctl call io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 io.netplan.Netplan.Config Get
s "network:\n ethernets:\n eth0:\n dhcp4: true\n renderer: networkd\n version: 2\n"
```
Write a new config snippet into `70-snapd.yaml`
```
$ busctl call io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 io.netplan.Netplan.Config Set ss "ethernets.eth0={dhcp4: false, dhcp6: true}" "70-snapd"
b true
```
Check the newly written configuration
```
$ busctl call io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 io.netplan.Netplan.Config Get
s "network:\n ethernets:\n eth0:\n dhcp4: false\n dhcp6: true\n renderer: networkd\n version: 2\n"
```
Try to apply the current config object's state
```
$ busctl call io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 io.netplan.Netplan.Config Try u 20
b true
```
Accept the Try() state within the 20 seconds timeout, if not it will be auto-rejected
```
$ busctl call io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 io.netplan.Netplan.Config Apply
b true
[SIGNAL] io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 io.netplan.Netplan.Config Changed() is triggered
[OBJECT] io.netplan.Netplan /io/netplan/Netplan/config/ULJIU0 is removed from the bus
```
Create a new config object and get the merged YAML config
```
$ busctl call io.netplan.Netplan /io/netplan/Netplan io.netplan.Netplan Config
o "/io/netplan/Netplan/config/KC0IU0
$ busctl call io.netplan.Netplan /io/netplan/Netplan/config/KC0IU0 io.netplan.Netplan.Config Get
s "network:\n ethernets:\n eth0:\n dhcp4: false\n dhcp6: true\n renderer: networkd\n version: 2\n"
```
Reject that config object again
```
$ busctl call io.netplan.Netplan /io/netplan/Netplan/config/KC0IU0 io.netplan.Netplan.Config Cancel
b true
[SIGNAL] io.netplan.Netplan /io/netplan/Netplan/config/KC0IU0 io.netplan.Netplan.Config Changed() is triggered
[OBJECT] io.netplan.Netplan /io/netplan/Netplan/config/KC0IU0 is removed from the bus
```
netplan-0.106.1/doc/example-config 0000664 0000000 0000000 00000003522 14431205264 0016711 0 ustar 00root root 0000000 0000000 network:
version: 2
# if specified, can only realistically have that value, as networkd cannot
# render wifi/3G. This would be shipped as a separate snippet by desktop images.
#renderer: NetworkManager
ethernets:
# opaque ID for physical interfaces, only referred to by other stanzas
id0:
match:
macaddress: 00:11:22:33:44:55
wakeonlan: true
dhcp4: true
addresses:
- 192.168.14.2/24
- "2001:1::1/64"
routes:
- to: default
via: 192.168.14.1
- to: default
via: "2001:1::2"
- to: 11.22.0.0/16
via: 192.168.14.3
metric: 100
nameservers:
search: [foo.local, bar.local]
addresses: [8.8.8.8]
lom:
match:
driver: ixgbe
# you are responsible for setting tight enough match rules
# that only match one device if you use set-name
set-name: lom1
dhcp6: true
switchports:
# all cards on second PCI bus; unconfigured by themselves, will be added
# to br0 below (note: globbing is not supported by NetworkManager)
match:
name: enp2*
mtu: 1280
wifis:
all-wlans:
# useful on a system where you know there is only ever going to be one device
match: {}
access-points:
"Joe's home":
# mode defaults to "managed" (client)
password: "s3kr1t"
# this creates an AP on wlp1s0 using hostapd; no match rules, thus ID is
# the interface name
wlp1s0:
access-points:
"guest":
mode: ap
# no WPA config implies default of open
bridges:
# the key name is the name for virtual (created) interfaces; no match: and
# set-name: allowed
br0:
# IDs of the components; switchports expands into multiple interfaces
interfaces: [wlp1s0, switchports]
dhcp4: true
netplan-0.106.1/doc/examples.md 0000664 0000000 0000000 00000040030 14431205264 0016223 0 ustar 00root root 0000000 0000000 # Introduction
Below is a collection of howtos for common scenarios.
If you see a scenario missing or have one to contribute, please file a bug
against this documentation with the example.
To configure Netplan, save configuration files under `/etc/netplan/` with a
`.yaml` extension (e.g. `/etc/netplan/config.yaml`), then run
`sudo netplan apply`. This command parses and applies the configuration to the
system. Configuration written to disk under `/etc/netplan/` will persist between
reboots.
For each of the example below, use the `renderer` that applies to your scenario. For example, for Ubuntu Desktop your `renderer` will probably be `NetworkManager` and `networkd` for Ubuntu Server.
Also, see [/examples](https://github.com/canonical/netplan/tree/main/examples)
on GitHub.
# How to enable DHCP on an interface
To let the interface named `enp3s0` get an address via DHCP, create a YAML file with the following:
```yaml
network:
version: 2
renderer: networkd
ethernets:
enp3s0:
dhcp4: true
```
# How to configure a static IP address on an interface
To set a static IP address, use the `addresses` keyword, which takes a list of (IPv4 or IPv6) addresses along with the subnet prefix length (e.g. /24).
```yaml
network:
version: 2
renderer: networkd
ethernets:
enp3s0:
addresses:
- 10.10.10.2/24
```
# How to configure DNS servers and search domains
The lists of search domains and DNS server IPs can be defined as below:
```yaml
network:
version: 2
renderer: networkd
ethernets:
enp3s0:
addresses:
- 10.10.10.2/24
nameservers:
search:
- "mycompany.local"
addresses:
- 10.10.10.253
- 8.8.8.8
```
# How to connect multiple interfaces with DHCP
DHCP can be used with multiple interfaces. The metrics for the routes acquired from DHCP can be changed with the use of DHCP overrides.
In this example, `enp5s0` is preferred over `enp6s0`, as it has a lower route metric:
```yaml
network:
version: 2
ethernets:
enp5s0:
dhcp4: yes
dhcp4-overrides:
route-metric: 100
enp6s0:
dhcp4: yes
dhcp4-overrides:
route-metric: 200
```
# How to connect to an open wireless network
For open wireless networks, Netplan only requires that the access point is defined. In this example, `opennetwork` is the network SSID:
```yaml
network:
version: 2
wifis:
wl0:
access-points:
opennetwork: {}
dhcp4: yes
```
# How to configure your computer to connect to your home wifi network
If all you need is to connect to your local domestic wifi network, use the configuration below:
```yaml
network:
version: 2
renderer: NetworkManager
wifis:
wlp2s0b1:
dhcp4: yes
access-points:
"network_ssid_name":
password: "**********"
```
# How to connect to a WPA Personal wireless network without DHCP
For private wireless networks, the access point name and password must be specified:
```yaml
network:
version: 2
renderer: networkd
wifis:
wlp2s0b1:
dhcp4: no
dhcp6: no
addresses: [192.168.0.21/24]
nameservers:
addresses: [192.168.0.1, 8.8.8.8]
access-points:
"network_ssid_name":
password: "**********"
routes:
- to: default
via: 192.168.0.1
```
# How to connect to WPA Enterprise wireless networks with EAP+TTLS
```yaml
network:
version: 2
wifis:
wl0:
access-points:
workplace:
auth:
key-management: eap
method: ttls
anonymous-identity: "@internal.example.com"
identity: "joe@internal.example.com"
password: "v3ryS3kr1t"
dhcp4: yes
```
# How to connect to WPA Enterprise wireless networks with EAP+TLS
```yaml
network:
version: 2
wifis:
wl0:
access-points:
university:
auth:
key-management: eap
method: tls
anonymous-identity: "@cust.example.com"
identity: "cert-joe@cust.example.com"
ca-certificate: /etc/ssl/cust-cacrt.pem
client-certificate: /etc/ssl/cust-crt.pem
client-key: /etc/ssl/cust-key.pem
client-key-password: "d3cryptPr1v4t3K3y"
dhcp4: yes
```
Many different modes of encryption are supported. See the [Netplan reference](/reference) page.
# How to use multiple addresses on a single interface
The `addresses` keyword can take a list of addresses to assign to an interface. You can also defined a `label` for each address:
```yaml
network:
version: 2
renderer: networkd
ethernets:
enp3s0:
addresses:
- 10.100.1.37/24
- 10.100.1.38/24:
label: "enp3s0:0"
- 10.100.1.39/24:
label: "enp3s0:some-label"
```
# How to use multiple addresses with multiple gateways
Similar to the example above, interfaces with multiple addresses can be configured with multiple gateways.
```yaml
network:
version: 2
renderer: networkd
ethernets:
enp3s0:
addresses:
- 10.0.0.10/24
- 11.0.0.11/24
routes:
- to: default
via: 10.0.0.1
metric: 200
- to: default
via: 11.0.0.1
metric: 300
```
We configure individual routes to default (or 0.0.0.0/0) using the address of the gateway for the subnet. The `metric` value should be adjusted so the routing happens as expected.
DHCP can be used to receive one of the IP addresses for the interface. In this case, the default route for that address will be automatically configured with a `metric` value of 100.
# How to use Network Manager as a renderer
Netplan supports both networkd and Network Manager as backends. You can specify which network backend should be used to configure particular devices by using the `renderer` key. You can also delegate all configuration of the network to Network Manager itself by specifying only the `renderer` key:
```yaml
network:
version: 2
renderer: NetworkManager
```
# How to configure interface bonding
Bonding is configured by declaring a bond interface with a list of physical interfaces and a bonding mode:
```yaml
network:
version: 2
renderer: networkd
bonds:
bond0:
dhcp4: yes
interfaces:
- enp3s0
- enp4s0
parameters:
mode: active-backup
primary: enp3s0
```
# How to configure multiple bonds
Below is an example of a system acting as a router with various bonded interfaces and different types. Note the 'optional: true' key declarations that allow booting to occur without waiting for those interfaces to activate fully.
```yaml
network:
version: 2
renderer: networkd
ethernets:
enp1s0:
dhcp4: no
enp2s0:
dhcp4: no
enp3s0:
dhcp4: no
optional: true
enp4s0:
dhcp4: no
optional: true
enp5s0:
dhcp4: no
optional: true
enp6s0:
dhcp4: no
optional: true
bonds:
bond-lan:
interfaces: [enp2s0, enp3s0]
addresses: [192.168.93.2/24]
parameters:
mode: 802.3ad
mii-monitor-interval: 1
bond-wan:
interfaces: [enp1s0, enp4s0]
addresses: [192.168.1.252/24]
nameservers:
search: [local]
addresses: [8.8.8.8, 8.8.4.4]
parameters:
mode: active-backup
mii-monitor-interval: 1
gratuitious-arp: 5
routes:
- to: default
via: 192.168.1.1
bond-conntrack:
interfaces: [enp5s0, enp6s0]
addresses: [192.168.254.2/24]
parameters:
mode: balance-rr
mii-monitor-interval: 1
```
# How to configure network bridges
Use the following configuration to create a simple bridge consisting of a single device that uses DHCP:
```yaml
network:
version: 2
renderer: networkd
ethernets:
enp3s0:
dhcp4: no
bridges:
br0:
dhcp4: yes
interfaces:
- enp3s0
```
# How to create a bridge with a VLAN for libvirtd
To get libvirtd to use a specific bridge with a tagged vlan, while continuing to provide an untagged interface as well would involve:
```yaml
network:
version: 2
renderer: networkd
ethernets:
enp0s25:
dhcp4: true
bridges:
br0:
addresses: [ 10.3.99.25/24 ]
interfaces: [ vlan15 ]
vlans:
vlan15:
accept-ra: no
id: 15
link: enp0s25
```
Then libvirtd would be configured to use this bridge by adding the following content to a new XML file under `/etc/libvirtd/qemu/networks/`. The name of the bridge in the <bridge> tag as well as in <name> need to match the name of the bridge device configured using netplan:
```xml
br0
```
# How to create VLANs
To configure multiple VLANs with renamed interfaces:
```yaml
network:
version: 2
renderer: networkd
ethernets:
mainif:
match:
macaddress: "de:ad:be:ef:ca:fe"
set-name: mainif
addresses: [ "10.3.0.5/23" ]
nameservers:
addresses: [ "8.8.8.8", "8.8.4.4" ]
search: [ example.com ]
routes:
- to: default
via: 10.3.0.1
vlans:
vlan15:
id: 15
link: mainif
addresses: [ "10.3.99.5/24" ]
vlan10:
id: 10
link: mainif
addresses: [ "10.3.98.5/24" ]
nameservers:
addresses: [ "127.0.0.1" ]
search: [ domain1.example.com, domain2.example.com ]
```
# How to use a directly connected gateway
This allows setting up a default route, or any route, using the "on-link" keyword where the gateway is an IP address that is directly connected to the network even if the address does not match the subnet configured on the interface.
```yaml
network:
version: 2
renderer: networkd
ethernets:
ens3:
addresses: [ "10.10.10.1/24" ]
routes:
- to: default # or 0.0.0.0/0
via: 9.9.9.9
on-link: true
```
For IPv6 the config would be very similar:
```yaml
network:
version: 2
renderer: networkd
ethernets:
ens3:
addresses: [ "2001:cafe:face:beef::dead:dead/64" ]
routes:
- to: default # or "::/0"
via: "2001:cafe:face::1"
on-link: true
```
# How to configure source routing
In the example below, ens3 is on the 192.168.3.0/24 network and ens5 is on the 192.168.5.0/24 network. This enables clients on either network to connect to the other and allow the response to come from the correct interface.
Furthermore, the default route is still assigned to ens5 allowing any other traffic to go through it.
```yaml
network:
version: 2
renderer: networkd
ethernets:
ens3:
addresses:
- 192.168.3.30/24
dhcp4: no
routes:
- to: 192.168.3.0/24
via: 192.168.3.1
table: 101
routing-policy:
- from: 192.168.3.0/24
table: 101
ens5:
addresses:
- 192.168.5.24/24
dhcp4: no
routes:
- to: default
via: 192.168.5.1
- to: 192.168.5.0/24
via: 192.168.5.1
table: 102
routing-policy:
- from: 192.168.5.0/24
table: 102
```
# How to configure a loopback interface
Networkd does not allow creating new loopback devices, but a user can add new addresses to the standard loopback interface, lo, in order to have it considered a valid address on the machine as well as for custom routing:
```yaml
network:
version: 2
renderer: networkd
ethernets:
lo:
addresses: [ "127.0.0.1/8", "::1/128", "7.7.7.7/32" ]
```
# How to integrate with Windows DHCP Server
For networks where DHCP is provided by a Windows Server using the dhcp-identifier keyword allows for interoperability:
```yaml
network:
version: 2
ethernets:
enp3s0:
dhcp4: yes
dhcp-identifier: mac
```
# How to connect to an IPv6 over IPv4 tunnel
Here, 1.1.1.1 is the client's own IP address; 2.2.2.2 is the remote server's IPv4 address, "2001:dead:beef::2/64" is the client's IPv6 address as defined by the tunnel, and "2001:dead:beef::1" is the remote server's IPv6 address.
Finally, "2001:cafe:face::1/64" is an address for the client within the routed IPv6 prefix:
```yaml
network:
version: 2
ethernets:
eth0:
addresses:
- 1.1.1.1/24
- "2001:cafe:face::1/64"
routes:
- to: default
via: 1.1.1.254
tunnels:
he-ipv6:
mode: sit
remote: 2.2.2.2
local: 1.1.1.1
addresses:
- "2001:dead:beef::2/64"
routes:
- to: default
via: "2001:dead:beef::1"
```
# How to configure SR-IOV Virtual Functions
For SR-IOV network cards, it is possible to dynamically allocate Virtual Function interfaces for every configured Physical Function. In netplan, a VF is defined by having a link: property pointing to the parent PF.
```yaml
network:
version: 2
ethernets:
eno1:
mtu: 9000
enp1s16f1:
link: eno1
addresses : [ "10.15.98.25/24" ]
vf1:
match:
name: enp1s16f[2-3]
link: eno1
addresses : [ "10.15.99.25/24" ]
```
# How to connect two systems with a WireGuard VPN
Generate the private and public keys in the first peer:
```bash
# wg genkey > private.key
# wg pubkey < private.key > public.key
# cat private.key
UMjI9WbobURkCDh2RT8SRM5osFI7siiR/sPOuuTIDns=
# cat public.key
EdNnZ1/2OJZ9HcScSVcwDVUsctCkKQ/xzjEyd3lZFFs=
```
Do the same in the second peer:
```bash
# wg genkey > private.key
# wg pubkey < private.key > public.key
# cat private.key
UAmjvLDVuV384OWFJkmI4bG8AIAZAfV7LarshnV3+lc=
# cat public.key
AIm+QeCoC23zInKASmhu6z/3iaT0R2IKraB7WwYB5ms=
```
Use the following configuration in the `first peer` (replace the keys and IPs as needed):
```yaml
network:
tunnels:
wg0:
mode: wireguard
port: 51820
key: UMjI9WbobURkCDh2RT8SRM5osFI7siiR/sPOuuTIDns=
addresses:
- 172.16.0.1/24
peers:
- allowed-ips: [172.16.0.0/24]
endpoint: 10.86.126.56:51820
keys:
public: AIm+QeCoC23zInKASmhu6z/3iaT0R2IKraB7WwYB5ms=
```
In the YAML file above, `key` is the first peer's `private key` and
`public` is the second peer's `public key`. `endpoint` is the `second peer` IP address.
Use the following configuration in the `second peer`:
```yaml
network:
tunnels:
wg0:
mode: wireguard
port: 51820
key: UAmjvLDVuV384OWFJkmI4bG8AIAZAfV7LarshnV3+lc=
addresses:
- 172.16.0.2/24
peers:
- allowed-ips: [172.16.0.0/24]
endpoint: 10.86.126.40:51820
keys:
public: EdNnZ1/2OJZ9HcScSVcwDVUsctCkKQ/xzjEyd3lZFFs=
```
In the YAML file above, `key` is the second peer's `private key` and
`public` is the first peer's `public key`. `endpoint` is the `first peer's` IP address.
# How to connect your home computer to a cloud instance with a WireGuard VPN
Follow the same steps from the previous howto to generate the necessary keys.
The difference here is that your computer is likely behind one or more devices doing NAT so you probably don't have a static public IP to use as endpoint in the remote system.
Use the following configuration in your computer:
```yaml
network:
tunnels:
wg0:
mode: wireguard
port: 51821
key: UMjI9WbobURkCDh2RT8SRM5osFI7siiR/sPOuuTIDns=
addresses:
- 172.17.0.1/24
peers:
- allowed-ips: [172.17.0.0/24]
endpoint: 54.234.x.y:51821
keys:
public: AIm+QeCoC23zInKASmhu6z/3iaT0R2IKraB7WwYB5ms=
```
Again, `key` is your private key and `public` is the remote system's public key. The `endpoint` is the public IP address of your instance.
In the remote instance you just need to omit the `endpoint`.
```yaml
network:
tunnels:
wg0:
mode: wireguard
port: 51821
key: UAmjvLDVuV384OWFJkmI4bG8AIAZAfV7LarshnV3+lc=
addresses:
- 172.17.0.2/24
peers:
- allowed-ips: [172.17.0.0/24]
keys:
public: EdNnZ1/2OJZ9HcScSVcwDVUsctCkKQ/xzjEyd3lZFFs=
```
Don't forget to allow the UDP port `51821` in your instance's security group.
After applying your configuration you should be able to reach your remote instance through the IP address `172.17.0.2`.
netplan-0.106.1/doc/explanation.md 0000664 0000000 0000000 00000000450 14431205264 0016731 0 ustar 00root root 0000000 0000000 # Explanation
## General structure & IDs
```{toctree}
structure-id
```
## Design
Network configuration abstraction via systemd-generator
```{toctree}
Netplan Design
```
## FAQs
Find answers to common questions
```{toctree}
Netplan FAQs
```
netplan-0.106.1/doc/howto.md 0000664 0000000 0000000 00000000112 14431205264 0015542 0 ustar 00root root 0000000 0000000 # How-to guides
```{toctree}
examples
dbus-config
netplan-everywhere
```
netplan-0.106.1/doc/index.md 0000664 0000000 0000000 00000004317 14431205264 0015524 0 ustar 00root root 0000000 0000000 # Netplan documentation
```{toctree}
---
maxdepth: 2
hidden: true
---
tutorial
howto
reference
explanation
```
**Netplan** is a network configuration abstraction renderer.
It is a **utility for network configuration** on a Linux system. You create a
description of the required interfaces and define what each should do.
Netplan meets the need of **easy, descriptive network configuration** in YAML
across a versatile set of server, desktop, cloud or IoT installations.
It is useful for **administrators of a Linux system** who want to use a common
network configuration, controlling different backends like NetworkManager or
systemd-networkd.
## In this documentation
::::{grid} 1 1 2 2
:::{grid-item-card} **[Tutorial](/netplan-tutorial)**
:link: /netplan-tutorial
:link-type: doc
**Get started** - hands-on introduction to Netplan for new users
:::
:::{grid-item-card} **[How-to guides](/examples)**
:link: /examples
:link-type: doc
**Step-by-step guides** covering key operations and common tasks
:::
::::
::::{grid} 1 1 2 2
:reverse:
:::{grid-item-card} **[Reference](/reference)**
:link: /reference
:link-type: doc
**Technical information** - specifications, APIs, architecture
:::
:::{grid-item-card} **[Explanation](/explanation)**
:link: /explanation
:link-type: doc
**Discussion and clarification** of key topics
:::
::::
## Project and community
Netplan is a member of the Ubuntu family. It’s an open source project that
warmly welcomes community contributions, suggestions, fixes and constructive
feedback.
* **[Read our code of conduct](https://ubuntu.com/community/code-of-conduct)**:
As a community we adhere to the Ubuntu code of conduct.
* **[Get support](https://askubuntu.com/questions/tagged/netplan)**:
Ask Ubuntu is a question and answer site for Ubuntu users and developers.
* **[Join our online chat](https://web.libera.chat/gamja/?channels=%23netplan)**:
Meet us in #netplan on IRC Libera.Chat.
* **[Report bugs](https://bugs.launchpad.net/netplan/+filebug)**:
We want to know about the problems so we can fix them.
* **[Contribute code](https://github.com/canonical/netplan)**:
The code is open and we are open to accepting changes to it.
Thinking about using Netplan? [Get in touch!](https://netplan.io)
netplan-0.106.1/doc/manpage-footer.md 0000664 0000000 0000000 00000000423 14431205264 0017313 0 ustar 00root root 0000000 0000000 # SEE ALSO
**netplan-generate**(8), **netplan-apply**(8), **netplan-try**(8), **netplan-get**(8), **netplan-set**(8), **netplan-info**(8), **netplan-ip**(8), **netplan-rebind**(8), **netplan-status**(8), **netplan-dbus**(8), **systemd-networkd**(8), **NetworkManager**(8)
netplan-0.106.1/doc/manpage-header.md 0000664 0000000 0000000 00000000613 14431205264 0017246 0 ustar 00root root 0000000 0000000 ---
title: netplan
section: 5
author:
- Mathieu Trudel-Lapierre ()
- Martin Pitt ()
- Lukas Märdian ()
...
# NAME
netplan - YAML network configuration abstraction for various backends
# SYNOPSIS
**netplan** [ *COMMAND* | help ]
# COMMANDS
See **netplan help** for a list of available commands on this system.
# DESCRIPTION
netplan-0.106.1/doc/meson.build 0000664 0000000 0000000 00000002436 14431205264 0016235 0 ustar 00root root 0000000 0000000 if pandoc.found()
custom_target(
input: ['manpage-header.md', 'structure-id.md', 'netplan-yaml.md', 'manpage-footer.md'],
output: 'netplan.5',
command: [pandoc, '-s', '-o', '@OUTPUT@', '--from=markdown-smart', '@INPUT@'],
install: true,
install_dir: join_paths(get_option('mandir'), 'man5'))
custom_target(
input: 'netplan-yaml.md',
output: 'netplan.html',
command: [pandoc, '-s', '--metadata', 'title="Netplan reference"', '--toc', '-o', '@OUTPUT@', '@INPUT@'],
install: true,
install_dir: join_paths(get_option('datadir'), 'doc', 'netplan'))
foreach doc : [
'netplan-apply', 'netplan-dbus', 'netplan-generate', 'netplan-get', 'netplan-set',
'netplan-try', 'netplan-info', 'netplan-ip', 'netplan-status', 'netplan-rebind',
]
markdown = files(doc + '.md')
manpage = doc + '.8'
custom_target(
input: markdown,
output: manpage,
command: [pandoc, '-s', '-o', '@OUTPUT@', '--shift-heading-level-by=-1', '--from=markdown-smart', '@INPUT@'],
install: true,
install_dir: join_paths(get_option('mandir'), 'man8'))
endforeach
else
warning('Program "pandoc" not found! Cannot generate documentation/man pages')
endif
netplan-0.106.1/doc/netplan-apply.md 0000664 0000000 0000000 00000004047 14431205264 0017201 0 ustar 00root root 0000000 0000000 ---
title: netplan-apply
section: 8
author:
- Daniel Axtens ()
...
## NAME
netplan-apply - apply configuration from netplan YAML files to a running system
## SYNOPSIS
**netplan** [--debug] **apply** -h | --help
**netplan** [--debug] **apply**
## DESCRIPTION
**netplan apply** applies the current netplan configuration to a running system.
The process works as follows:
1. The backend configuration is generated from netplan YAML files.
2. The appropriate backends (**systemd-networkd**(8) or
**NetworkManager**(8)) are invoked to bring up configured interfaces.
3. **netplan apply** iterates through interfaces that are still down, unbinding
them from their drivers, and rebinding them. This gives **udev**(7) renaming
rules the opportunity to run.
4. If any devices have been rebound, the appropriate backends are re-invoked in
case more matches can be done.
For information about the generation step, see
**netplan-generate**(8). For details of the configuration file format,
see **netplan**(5).
## OPTIONS
-h, --help
: Print basic help.
--debug
: Print debugging output during the process.
## KNOWN ISSUES
**netplan apply** will not remove virtual devices such as bridges and bonds
that have been created, even if they are no longer described in the netplan
configuration. That is due to the fact that netplan operates statelessly and
is not aware of the previously defined virtual devices.
This can be resolved by manually removing the virtual device (for example
``ip link delete dev bond0``) and then running **netplan apply**, by rebooting,
or by creating a temporary backup of the YAML state in ``/etc/netplan``
before modifying the configuration and passing this state to netplan (e.g.
``mkdir -p /tmp/netplan_state_backup/etc && cp -r /etc/netplan /tmp/netplan_state_backup/etc/``
then running **netplan apply --state /tmp/netplan_state_backup**)
## SEE ALSO
**netplan**(5), **netplan-generate**(8), **netplan-try**(8), **udev**(7),
**systemd-networkd.service**(8), **NetworkManager**(8)
netplan-0.106.1/doc/netplan-dbus.md 0000664 0000000 0000000 00000005212 14431205264 0017004 0 ustar 00root root 0000000 0000000 ---
title: netplan-dbus
section: 8
author:
- Lukas Märdian ()
...
## NAME
netplan-dbus - daemon to access netplan's functionality via a DBus API
## SYNOPSIS
**netplan-dbus**
## DESCRIPTION
**netplan-dbus** is a DBus daemon, providing ``io.netplan.Netplan`` on the system bus. The ``/io/netplan/Netplan`` object provides an ``io.netplan.Netplan`` interface, offering the following methods:
* ``Apply() -> b``: calls **netplan apply** and returns a success or failure status.
* ``Generate() -> b``: calls **netplan generate** and returns a success or failure status.
* ``Info() -> a(sv)``: returns a dict "Features -> as", containing an array of all available feature flags.
* ``Config() -> o``: prepares a new config object as ``/io/netplan/Netplan/config/``, by copying the current state from ``/{etc,run,lib}/netplan/*.yaml``
The ``/io/netplan/Netplan/config/`` objects provide a ``io.netplan.Netplan.Config`` interface, offering the following methods:
* ``Get() -> s``: calls **netplan get --root-dir=/run/netplan/config-ID all** and returns the merged YAML config of the the given config object's state
* ``Set(s:CONFIG_DELTA, s:ORIGIN_HINT) -> b``: calls **netplan set --root-dir=/run/netplan/config-ID --origin-hint=ORIGIN_HINT CONFIG_DELTA**
CONFIG_DELTA can be something like: ``network.ethernets.eth0.dhcp4=true`` and
ORIGIN_HINT can be something like: ``70-snapd`` (it will then write the config
to ``70-snapd.yaml``). Once ``Set()`` is called on a config object, all other
current and future config objects are being invalidated and cannot ``Set()`` or
``Try()/Apply()`` anymore, due to this pending dirty state. After the dirty
config object is rejected via ``Cancel()``, the other config objects are valid
again. If the dirty config object is accepted via ``Apply()``, newly created
config objects will be valid, while the older states will stay invalid.
* ``Try(u:TIMEOUT_SEC) -> b``: replaces the main netplan configuration with this config object's state and calls **netplan try --timeout=TIMEOUT_SEC**
* ``Cancel() -> b``: rejects a currently running ``Try()`` attempt on this config object and/or discards the config object
* ``Apply() -> b``: replaces the main netplan configuration with this config object's state and calls **netplan apply**
For information about the Apply()/Try()/Get()/Set() functionality, see
**netplan-apply**(8)/**netplan-try**(8)/**netplan-get**(8)/**netplan-set**(8)
accordingly. For details of the configuration file format, see **netplan**(5).
## SEE ALSO
**netplan**(5), **netplan-apply**(8), **netplan-try**(8), **netplan-get**(8),
**netplan-set**(8)
netplan-0.106.1/doc/netplan-everywhere.md 0000664 0000000 0000000 00000012615 14431205264 0020241 0 ustar 00root root 0000000 0000000 # Desktop integration
## NetworkManager YAML settings backend (Netplan everywhere)
NetworkManager is the tool used by Ubuntu Desktop systems to manage
network devices such as Ethernet and Wifi adapters. While it is a great
tool for the job and users can directly use it through the command line
and the graphical interfaces to configure their devices, Ubuntu has its
own way of describing and storing network configuration via Netplan.
On Ubuntu, NetworkManager uses (or will use, depending on when you are
reading this) Netplan's APIs to save the configuration created by the
user using any of its interfaces. Our goal is to have a centralized place
to store network configuration. In the Desktop it's convenient to use
graphical tools for configuration when they are available, so nothing will
change from the user perspective, only the way the configuration is
handled under the hood.
For more information on Netplan, check https://netplan.io/
For more information on NetworkManager, check https://networkmanager.dev/
## How it works
Every time a non-temporary connection is created in NetworkManager, instead
of persisting the original .nmconnection file, it will create a Netplan YAML
at `/etc/netplan` called `90-NM-.yaml`. After creating the
file, NetworkManager will call the Netplan generator to emit the configuration
for that connection. Connections that are temporary, like the ones created
for virtual network interfaces when you connect to a VPN for example, are not
persisted as Netplan files. The reason for that is that these interfaces are
usually managed by external services and we don't want to cause any unexpected
change that would affect them.
## How to install it
### Creating a backup of your current configuration
The new NetworkManager will remove connection profiles that you eventually
modify from `/etc/NetworkManager`. So you might want to create a copy of all
your connection profiles before installing the new network-manager package:
```
$ mkdir ~/NetworkManager.bak && cd ~/NetworkManager.bak/
$ sudo cp -r /etc/NetworkManager/system-connections .
```
In any case, a backup will be created automatically for you at
`/root/NetworkManager.bak` during package installation.
And also keep a copy of all the original network-manager related packages in
case you want to revert to the previous installation:
```
$ apt download gir1.2-nm-1.0 libnm0 network-manager network-manager-config-connectivity-ubuntu
```
### Installing NetworkManager
The NetworkManager 1.42.0 package containing the Netplan integration patch
is currently available as a PPA. In order to install it, you will need to
have `netplan.io >= 0.106` installed in your system (it is available in Lunar).
```
$ sudo add-apt-repository ppa:canonical-foundations/networkmanager-netplan
$ sudo apt update
$ sudo apt install network-manager
```
## How connections are managed from now on
After installing the new NetworkManager, your existing connection profiles
will not be imported to Netplan YAML files, only new connections and the
existing ones you eventually modify.
For example, if you have a Wifi connection, you will find the connection
profile file at `/etc/NetworkManager/system-connections`. If you modify it
using one of the NetworkManager's interfaces (or delete and create a new one),
the respective file will be removed from `/etc/NetworkManager/system-connections`,
a Netplan YAML called `90-NM-.yaml` will be created at
`/etc/netplan` and a new profile will be generated and stored at
`/run/NetworkManager/system-connections`.
## Limitation
Netplan doesn't yet support all the configuration available in
NetworkManager (or doesn't know how to interpret some of the keywords
found in the keyfile). After creating a new connection you might find
a section called "passthrough" in your YAML file, like in the example below:
```yaml
network:
version: 2
ethernets:
NM-0f7a33ac-512e-4c03-b088-4db00fe3292e:
renderer: NetworkManager
match:
name: "enp1s0"
nameservers:
addresses:
- 8.8.8.8
dhcp4: true
wakeonlan: true
networkmanager:
uuid: "0f7a33ac-512e-4c03-b088-4db00fe3292e"
name: "Ethernet connection 1"
passthrough:
ethernet._: ""
ipv4.ignore-auto-dns: "true"
ipv6.addr-gen-mode: "default"
ipv6.method: "disabled"
ipv6.ip6-privacy: "-1"
proxy._: ""
```
All the configuration under the "passthrough" mapping will be added to
the `.nmconnection` file as they are.
In cases where the connection type is not supported by Netplan the
`nm-devices` network type will be used. The example below is an OpenVPN
client connection, which is not supported by Netplan at the moment.
```yaml
network:
version: 2
nm-devices:
NM-db5f0f67-1f4c-4d59-8ab8-3d278389cf87:
renderer: NetworkManager
networkmanager:
uuid: "db5f0f67-1f4c-4d59-8ab8-3d278389cf87"
name: "myvpnconnection"
passthrough:
connection.type: "vpn"
vpn.ca: "path to ca.crt"
vpn.cert: "path to client.crt"
vpn.cipher: "AES-256-GCM"
vpn.connection-type: "tls"
vpn.dev: "tun"
vpn.key: "path to client.key"
vpn.remote: "1.2.3.4:1194"
vpn.service-type: "org.freedesktop.NetworkManager.openvpn"
ipv4.method: "auto"
ipv6.addr-gen-mode: "default"
ipv6.method: "auto"
proxy._: ""
```
netplan-0.106.1/doc/netplan-generate.md 0000664 0000000 0000000 00000005201 14431205264 0017637 0 ustar 00root root 0000000 0000000 ---
title: netplan-generate
section: 8
author:
- Daniel Axtens ()
...
## NAME
netplan-generate - generate backend configuration from netplan YAML files
## SYNOPSIS
**netplan** [--debug] **generate** -h | --help
**netplan** [--debug] **generate** [--root-dir _ROOT_DIR_] [--mapping _MAPPING_]
## DESCRIPTION
netplan generate converts netplan YAML into configuration files
understood by the backends (**systemd-networkd**(8) or
**NetworkManager**(8)). It *does not* apply the generated
configuration.
You will not normally need to run this directly as it is run by
**netplan apply**, **netplan try**, or at boot.
Only if executed during the systemd ``initializing`` phase
(i.e. "Early bootup, before ``basic.target`` is reached"), will
it attempt to start/apply the newly created service units.
**Requires feature: generate-just-in-time**
For details of the configuration file format, see **netplan**(5).
## OPTIONS
-h, --help
: Print basic help.
--debug
: Print debugging output during the process.
--root-dir _ROOT_DIR_
: Instead of looking in /{lib,etc,run}/netplan, look in
/_ROOT_DIR_/{lib,etc,run}/netplan
--mapping _MAPPING_
: Instead of generating output files, parse the configuration files
and print some internal information about the device specified in
_MAPPING_.
## HANDLING MULTIPLE FILES
There are 3 locations that netplan generate considers:
* /lib/netplan/*.yaml
* /etc/netplan/*.yaml
* /run/netplan/*.yaml
If there are multiple files with exactly the same name, then only one
will be read. A file in /run/netplan will shadow - completely replace
- a file with the same name in /etc/netplan. A file in /etc/netplan
will itself shadow a file in /lib/netplan.
Or in other words, /run/netplan is top priority, then /etc/netplan,
with /lib/netplan having the lowest priority.
If there are files with different names, then they are considered in
lexicographical order - regardless of the directory they are in. Later
files add to or override earlier files. For example,
/run/netplan/10-foo.yaml would be updated by /lib/netplan/20-abc.yaml.
If you have two files with the same key/setting, the following rules
apply:
* If the values are YAML boolean or scalar values (numbers and
strings) the old value is overwritten by the new value.
* If the values are sequences, the sequences are concatenated - the
new values are appended to the old list.
* If the values are mappings, netplan will examine the elements
of the mappings in turn using these rules.
## SEE ALSO
**netplan**(5), **netplan-apply**(8), **netplan-try**(8),
**systemd-networkd**(8), **NetworkManager**(8)
netplan-0.106.1/doc/netplan-get.md 0000664 0000000 0000000 00000001602 14431205264 0016625 0 ustar 00root root 0000000 0000000 ---
title: netplan-get
section: 8
author:
- Lukas Märdian (lukas.maerdian@canonical.com)
...
## NAME
netplan-get - read merged netplan YAML configuration
## SYNOPSIS
**netplan** [--debug] **get** -h | --help
**netplan** [--debug] **get** [--root-dir=ROOT_DIR] [key]
## DESCRIPTION
**netplan get [key]** reads all YAML files from ``/{etc,lib,run}/netplan/*.yaml`` and returns a merged view of the current configuration
You can specify ``all`` as a key (the default) to get the full YAML tree or extract a subtree by specifying a nested key like: ``[network.]ethernets.eth0``.
For details of the configuration file format, see **netplan**(5).
## OPTIONS
-h, --help
: Print basic help.
--debug
: Print debugging output during the process.
--root-dir
: Read YAML files from this root instead of /
## SEE ALSO
**netplan**(5), **netplan-set**(8), **netplan-dbus**(8)
netplan-0.106.1/doc/netplan-info.md 0000664 0000000 0000000 00000001125 14431205264 0017001 0 ustar 00root root 0000000 0000000 ---
title: netplan-info
section: 8
author:
- Danilo Egea Gondolfo (danilo.egea.gondolfo@canonical.com)
...
## NAME
netplan-info - show available features
## SYNOPSIS
**netplan** [--debug] **info** -h | --help
**netplan** [--debug] **info** [--json | --yaml]
## DESCRIPTION
**netplan info** displays the supported features.
## OPTIONS
-h, --help
: Print basic help.
--debug
: Print debugging output during the process.
--json
: Output version and features in JSON format.
--yaml
: Output version and features in YAML format (default).
## SEE ALSO
**netplan**(5)
netplan-0.106.1/doc/netplan-ip.md 0000664 0000000 0000000 00000001361 14431205264 0016460 0 ustar 00root root 0000000 0000000 ---
title: netplan-ip
section: 8
author:
- Danilo Egea Gondolfo (danilo.egea.gondolfo@canonical.com)
...
## NAME
netplan-ip - retrieve IP information (like DHCP leases) from the system
## SYNOPSIS
**netplan** [--debug] **ip** -h | --help
**netplan** [--debug] **ip** COMMAND [--root-dir=ROOT_DIR] ARGUMENTS
## DESCRIPTION
**netplan ip** retrieves IP information (like DHCP leases) from the system.
## DHCP COMMANDS
**leases** `INTERFACE`: Displays DHCP IP leases
Example: netplan ip leases enp5s0
## OPTIONS
-h, --help
: Print basic help.
--debug
: Print debugging output during the process.
--root-dir
: Read YAML files from this root instead of /
## SEE ALSO
**netplan**(5), **netplan-get**(8), **netplan-status**(8)
netplan-0.106.1/doc/netplan-rebind.md 0000664 0000000 0000000 00000001226 14431205264 0017313 0 ustar 00root root 0000000 0000000 ---
title: netplan-rebind
section: 8
author:
- Danilo Egea Gondolfo (danilo.egea.gondolfo@canonical.com)
...
## NAME
netplan-rebind - rebind SR-IOV virtual functions to their driver
## SYNOPSIS
**netplan** [--debug] **rebind** -h | --help
**netplan** [--debug] **rebind** [interfaces]
## DESCRIPTION
**netplan rebind [interfaces]** rebinds SR-IOV virtual functions of given physical functions to their driver.
## OPTIONS
-h, --help
: Print basic help.
--debug
: Print debugging output during the process.
interfaces
: Space separated list of PF interface names.
## SEE ALSO
**netplan**(5), **netplan-set**(8), **netplan-apply**(8)
netplan-0.106.1/doc/netplan-set.md 0000664 0000000 0000000 00000002105 14431205264 0016640 0 ustar 00root root 0000000 0000000 ---
title: netplan-set
section: 8
author:
- Lukas Märdian (lukas.maerdian@canonical.com)
...
## NAME
netplan-set - write netplan YAML configuration snippets to file
## SYNOPSIS
**netplan** [--debug] **set** -h | --help
**netplan** [--debug] **set** [--root-dir=ROOT_DIR] [--origin-hint=ORIGIN_HINT] [key=value]
## DESCRIPTION
**netplan set [key=value]** writes a given key/value pair or YAML subtree into a YAML file in ``/etc/netplan/`` and validates its format.
You can specify a single value as: ``"[network.]ethernets.eth0.addresses=[1.2.3.4/24, 5.6.7.8/24]"`` or a full subtree as: ``"[network.]ethernets.eth0={dhcp4: true, dhcp6: true}"``.
For details of the configuration file format, see **netplan**(5).
## OPTIONS
-h, --help
: Print basic help.
--debug
: Print debugging output during the process.
--root-dir
: Write YAML files into this root instead of /
--origin-hint
: Specify a name for the config file, e.g.: ``70-netplan-set`` => ``/etc/netplan/70-netplan-set.yaml``
## SEE ALSO
**netplan**(5), **netplan-get**(8), **netplan-dbus**(8)
netplan-0.106.1/doc/netplan-status.md 0000664 0000000 0000000 00000001663 14431205264 0017400 0 ustar 00root root 0000000 0000000 ---
title: netplan-status
section: 8
author:
- Danilo Egea Gondolfo (danilo.egea.gondolfo@canonical.com)
...
## NAME
netplan-status - query networking state of the running system
## SYNOPSIS
**netplan** [--debug] **status** -h | --help
**netplan** [--debug] **status** [interface]
## DESCRIPTION
**netplan status [interface]** queries the current network configuration and displays it in human readable format.
You can specify ``interface`` to display the status of a specific interface.
Currently, **netplan status** depends on `systemd-networkd` as a source of data and will try to start it if it's not masked.
## OPTIONS
-h, --help
: Print basic help.
--debug
: Print debugging output during the process.
-a, --all
: Show all interface data including inactive
-f FORMAT, --format FORMAT
: Output in machine readable `json` or `yaml` format
## SEE ALSO
**netplan**(5), **netplan-get**(8), **netplan-ip**(8)
netplan-0.106.1/doc/netplan-try.md 0000664 0000000 0000000 00000003314 14431205264 0016666 0 ustar 00root root 0000000 0000000 ---
title: netplan-try
section: 8
author:
- Daniel Axtens ()
...
## NAME
netplan-try - try a configuration, optionally rolling it back
## SYNOPSIS
**netplan** [--debug] **try** -h | --help
**netplan** [--debug] **try** [--config-file _CONFIG_FILE_] [--timeout _TIMEOUT_]
## DESCRIPTION
**netplan try** takes a **netplan**(5) configuration, applies it, and
automatically rolls it back if the user does not confirm the
configuration within a time limit.
A configuration can be confirmed or rejected interactively or by sending the
SIGUSR1 or SIGINT signals.
This may be especially useful on remote systems, to prevent an
administrator being permanently locked out of systems in the case of a
network configuration error.
## OPTIONS
-h, --help
: Print basic help.
--debug
: Print debugging output during the process.
--config-file _CONFIG_FILE_
: In addition to the usual configuration, apply _CONFIG_FILE_. It must
be a YAML file in the **netplan**(5) format.
--timeout _TIMEOUT_
: Wait for _TIMEOUT_ seconds before reverting. Defaults to 120
seconds. Note that some network configurations (such as STP) may take
over a minute to settle.
## KNOWN ISSUES
**netplan try** uses similar procedures to **netplan apply**, so some
of the same caveats apply around virtual devices.
There are also some known bugs: if **netplan try** times out or is
cancelled, make sure to verify if the network configuration has in
fact been reverted.
As with **netplan apply**, a reboot should fix any issues. However, be
sure to verify that the config on disk is in the state you expect
before rebooting!
## SEE ALSO
**netplan**(5), **netplan-generate**(8), **netplan-apply**(8)
netplan-0.106.1/doc/netplan-tutorial.md 0000664 0000000 0000000 00000050563 14431205264 0017723 0 ustar 00root root 0000000 0000000 # Pre-requisites
In order to do the exercises yourself you will need a virtual machine, preferably running Ubuntu. In this tutorial, we will use LXD to create virtual networks and launch virtual machines. Feel free to use a cloud instance or a different hypervisor. As long as you can achieve the same results, you should be fine. If you're going to use your own desktop/laptop system, some of the exercises might interrupt your network connectivity.
If you already have a setup where you can do the exercises you can just skip this section.
## Setting up the environment
You can follow the steps below to install and create a basic LXD configuration you can use to launch virtual machines.
For more information about LXD, please visit [linuxcontainers.org](https://linuxcontainers.org/lxd/introduction/).
First, install LXD: [LXD | How to install LXD](https://linuxcontainers.org/lxd/docs/latest/installing/)
On Ubuntu, you can install it using `snap`:
```
$ snap install lxd
```
Now, initialize your LXD configuration:
```
$ lxd init --minimal
```
Run the command below to create a new network in LXD. For some of the exercises you will need a second network interface in your virtual machine.
```
lxc network create netplanbr0 --type=bridge
```
You should see the output below:
```
Network netplanbr0 created
```
At this point you should have a usable LXD installation with a working network bridge.
Now create a virtual machine called `netplan-lab0`:
```
lxc init --vm ubuntu:22.04 netplan-lab0
```
You should see the output below:
```
Creating netplan-lab0
```
The new VM will have one network interface attached to the default LXD bridge.
Now attach the network you created just now, `netplanbr0`, to your VM, `netplan-lab0`, as interface `eth1`:
```
lxc network attach netplanbr0 netplan-lab0 eth1
```
> See more: [LXD | Attach a network to an instance](https://linuxcontainers.org/lxd/docs/latest/howto/network_create/#attach-a-network-to-an-instance)
And start your new VM:
```
lxc start netplan-lab0
```
Access your new VM using `lxc shell`:
```
lxc shell netplan-lab0
```
> **If this doesn't work for you**: Try instead `lxc exec netplan-lab0 bash` or `lxc console netplan-lab0`.
You should now have a root shell inside your VM:
```
root@netplan-lab0:~#
```
Run the command `ip link` to show your network interfaces:
```
ip link
```
You should see an output similar to the below:
```
1: lo: mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: enp5s0: mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000
link/ether 00:16:3e:13:ae:10 brd ff:ff:ff:ff:ff:ff
3: enp6s0: mtu 1500 qdisc noop state DOWN mode DEFAULT group default qlen 1000
link/ether 00:16:3e:0c:97:8a brd ff:ff:ff:ff:ff:ff
```
In this case, `enp5s0` is the primary interface connected to the default LXD network and `enp6s0` is the second interface you added connected to your custom network.
Now, let's start with a simple exercise.
# Running netplan for the first time
Start by typing the command `netplan` in your shell:
```
netplan
```
You should see the output below
```
You need to specify a command
usage: /usr/sbin/netplan [-h] [--debug] ...
Network configuration in YAML
options:
-h, --help show this help message and exit
--debug Enable debug messages
Available commands:
help Show this help message
apply Apply current netplan config to running system
generate Generate backend specific configuration files from /etc/netplan/*.yaml
get Get a setting by specifying a nested key like "ethernets.eth0.addresses", or "all"
info Show available features
ip Retrieve IP information from the system
set Add new setting by specifying a dotted key=value pair like ethernets.eth0.dhcp4=true
rebind Rebind SR-IOV virtual functions of given physical functions to their driver
status Query networking state of the running system
try Try to apply a new netplan config to running system, with automatic rollback
```
As you can see, netplan has a number of sub commands. Let's explore some of them.
# Showing your current netplan configuration
To show your current configuration, run the command `netplan get`.
```
netplan get
```
You should see an output similar to the one below:
```yaml
network:
version: 2
ethernets:
enp5s0:
dhcp4: true
```
It shows you have an ethernet interface called `enp5s0` and it has DHCP enabled for IPv4.
# Showing your current network configuration
Netplan 0.106 introduced the `netplan status` command. You can use it to
show your system's current network configuration. Try that by typing
`netplan status --all` in your console:
```
netplan status --all
```
You should see an output similar to the one below:
```
Online state: online
DNS Addresses: 127.0.0.53 (stub)
DNS Search: lxd
● 1: lo ethernet UNKNOWN/UP (unmanaged)
MAC Address: 00:00:00:00:00:00
Addresses: 127.0.0.1/8
::1/128
Routes: ::1 metric 256
● 2: enp5s0 ethernet UP (networkd: enp5s0)
MAC Address: 00:16:3e:13:ae:10 (Red Hat, Inc.)
Addresses: 10.86.126.221/24 (dhcp)
fd42:bc43:e20e:8cf7:216:3eff:fe13:ae10/64
fe80::216:3eff:fe13:ae10/64 (link)
DNS Addresses: 10.86.126.1
fe80::216:3eff:feab:beb9
DNS Search: lxd
Routes: default via 10.86.126.1 from 10.86.126.221 metric 100 (dhcp)
10.86.126.0/24 from 10.86.126.221 metric 100 (link)
10.86.126.1 from 10.86.126.221 metric 100 (dhcp, link)
fd42:bc43:e20e:8cf7::/64 metric 100 (ra)
fe80::/64 metric 256
default via fe80::216:3eff:feab:beb9 metric 100 (ra)
● 3: enp6s0 ethernet DOWN (unmanaged)
MAC Address: 00:16:3e:0c:97:8a (Red Hat, Inc.)
```
# Checking the file where your configuration is stored
The configuration you just listed is stored at `/etc/netplan`. You can see the contents of the file with the command below:
```
cat /etc/netplan/50-cloud-init.yaml
```
You should see an output similar to this:
```yaml
# This file is generated from information provided by the datasource. Changes
# to it will not persist across an instance reboot. To disable cloud-init's
# network configuration capabilities, write a file
# /etc/cloud/cloud.cfg.d/99-disable-network-config.cfg with the following:
# network: {config: disabled}
network:
version: 2
ethernets:
enp5s0:
dhcp4: true
```
This file was automatically generated by `cloud-init` when the system was initialized. As noted in the comments, changes to this file will not persist.
# Enabling your second network interface with DHCP
There are basically 2 ways to create or change netplan configuration:
1) Using the `netplan set` command
2) Editing the YAML files manually
Let's see how you can enable your second network interface using both ways.
## Using `netplan set`
For simple tasks, you can use `netplan set` to change your configuration.
In the example below you are going to create a new YAML file called `second-interface.yaml` containing only the configuration needed to enable our second interfaces.
Considering your second network interface is `enp6s0`, run the command below:
```
netplan set --origin-hint second-interface ethernets.enp6s0.dhcp4=true
```
The command line parameter `--origin-hint` sets the name of the file where the configuration will be stored.
Now list the files in the directory `/etc/netplan`:
```
ls /etc/netplan
```
You should see the auto generated cloud-init file and a new file called `second-interface.yaml`:
```
root@netplan-lab0:~# ls /etc/netplan/
50-cloud-init.yaml second-interface.yaml
```
Use the command `cat` to see its content:
```
cat /etc/netplan/second-interface.yaml
```
```yaml
network:
version: 2
ethernets:
enp6s0:
dhcp4: true
```
You will notice it is very similar to the one generated by cloud-init.
Now use `netplan get` to see your full configuration:
```
netplan get
```
You should see an output similar to the one below with both ethernet interfaces:
```yaml
network:
version: 2
ethernets:
enp5s0:
dhcp4: true
enp6s0:
dhcp4: true
```
## Applying your new configuration
The command `netplan set` created the configuration for your second network interface but it wasn't applied to the running system.
Run the command below to see the current state of your second network interface:
```
ip address show enp6s0
```
You should see an output similar to the one below:
```
3: enp6s0: mtu 1500 qdisc noop state DOWN group default qlen 1000
link/ether 00:16:3e:0c:97:8a brd ff:ff:ff:ff:ff:ff
```
As you can see, this interface has no IP address and its state is DOWN.
In order to apply the netplan configuration, you can use the command `netplan apply`.
Run the command below in your shell:
```
netplan apply
```
Now check again the state of the interface `enp6s0`:
```
ip address show enp6s0
```
You should see an output similar to this:
```
3: enp6s0: mtu 1500 qdisc mq state UP group default qlen 1000
link/ether 00:16:3e:0c:97:8a brd ff:ff:ff:ff:ff:ff
inet 10.33.59.157/24 metric 100 brd 10.33.59.255 scope global dynamic enp6s0
valid_lft 3589sec preferred_lft 3589sec
inet6 fd42:ee65:61d0:abcb:216:3eff:fe0c:978a/64 scope global dynamic mngtmpaddr noprefixroute
valid_lft 3599sec preferred_lft 3599sec
inet6 fe80::216:3eff:fe0c:978a/64 scope link
valid_lft forever preferred_lft forever
```
You can also use `netplan status` to check the interface:
```
netplan status enp6s0
```
You should see an output similar to this:
```
Online state: online
DNS Addresses: 127.0.0.53 (stub)
DNS Search: lxd
● 3: enp6s0 ethernet UP (networkd: enp6s0)
MAC Address: 00:16:3e:0c:97:8a (Red Hat, Inc.)
Addresses: 10.33.59.157/24 (dhcp)
fd42:ee65:61d0:abcb:216:3eff:fe0c:978a/64
fe80::216:3eff:fe0c:978a/64 (link)
DNS Addresses: 10.33.59.1
fe80::216:3eff:fea1:585b
DNS Search: lxd
Routes: default via 10.33.59.1 from 10.33.59.157 metric 100 (dhcp)
10.33.59.0/24 from 10.33.59.157 metric 100 (link)
10.33.59.1 from 10.33.59.157 metric 100 (dhcp, link)
fd42:ee65:61d0:abcb::/64 metric 100 (ra)
fe80::/64 metric 256
2 inactive interfaces hidden. Use "--all" to show all.
```
As you can see, even though you haven't enabled DHCP for IPv6 on this interface, the network configuration backend (in this case systemd-networkd) enabled it anyway. But let's assume you want only IPv4.
Let's address this situation in the next exercise.
## Editing YAML files
For more complex configuration, you can just create or edit a new file yourself using your favorite text editor.
Continuing the exercise from the previous section, let's go ahead and disable automatic IPv6 configuration on your second interface. But this time let's do it by manually editing the YAML file.
Use your favorite text editor and open the file `/etc/netplan/second-interface.yaml`.
Add the configuration below to the interface configuration section:
```yaml
accept-ra: false
link-local: []
```
When you finish, it should look like this:
```yaml
network:
version: 2
ethernets:
enp6s0:
dhcp4: true
accept-ra: false
link-local: []
```
With this new configuration, the network configuration backend (systemd-networkd in this case) will not accept Route Advertisements and will not add the link-local address to our interface.
Now check your new configuration with the `netplan get` command:
```
netplan get
```
You should see something similar to this:
```yaml
network:
version: 2
ethernets:
enp5s0:
dhcp4: true
enp6s0:
dhcp4: true
accept-ra: false
link-local: []
```
Now use `netplan apply` to apply your new configuration:
```
netplan apply
```
And check your interface configuration:
```
ip address show enp6s0
```
You should see an output similar to this:
```
3: enp6s0: mtu 1500 qdisc mq state UP group default qlen 1000
link/ether 00:16:3e:0c:97:8a brd ff:ff:ff:ff:ff:ff
inet 10.33.59.157/24 metric 100 brd 10.33.59.255 scope global dynamic enp6s0
valid_lft 3585sec preferred_lft 3585sec
```
And as you can see, now it only has an IPv4 address.
In this exercise you explored the `netplan set`, `netplan get`, `netplan apply` and `netplan status` commands. You also used some of the ethernet configuration options to get a network interface up and running with DHCP.
# Using static IP addresses
In this exercise you're going to add an static IP address to the second interface with a default route and DNS configuration.
Use your favorite text editor to open the file `/etc/netplan/second-interface.yaml` created previously. Change it so it will look like this:
```yaml
network:
version: 2
ethernets:
enp6s0:
dhcp4: false
dhcp6: false
accept-ra: false
link-local: []
addresses:
- 172.16.0.1/24
routes:
- to: default
via: 172.16.0.254
nameservers:
search:
- netplanlab.local
addresses:
- 172.16.0.254
- 172.16.0.253
```
The configuration above is what you'd expect in a desktop system for example. It defines the interface's IP address statically as `172.16.0.1/24`, a default route via gateway `172.16.0.254` and the DNS search domain and nameservers.
Now use `netplan get` to visualize all your network configuration:
```
netplan get
```
You should see an output similar to this:
```yaml
network:
version: 2
ethernets:
enp5s0:
dhcp4: true
enp6s0:
addresses:
- "172.16.0.1/24"
nameservers:
addresses:
- 172.16.0.254
- 172.16.0.253
search:
- netplanlab.local
dhcp4: false
dhcp6: false
accept-ra: false
routes:
- to: "default"
via: "172.16.0.254"
link-local: []
```
You will notice that it might be a little different than what you have defined in the YAML file. Some things might be in a different order for example.
The reason for that is that `netplan get` loads and parses your configuration before outputting it and the YAML parsing engine used by netplan might shuffle things around. Although, what you see from `netplan get` is equivalent to what you have in the file.
Now use `netplan apply` to apply the new configuration:
```
netplan apply
```
And check the interface's new state:
```
ip address show dev enp6s0
```
You should see something similar to this:
```
3: enp6s0: mtu 1500 qdisc mq state UP group default qlen 1000
link/ether 00:16:3e:0c:97:8a brd ff:ff:ff:ff:ff:ff
inet 172.16.0.1/24 brd 172.16.0.255 scope global enp6s0
valid_lft forever preferred_lft forever
```
Check the routes associated to the interface:
```
ip route show dev enp6s0
```
You should see something similar to this:
```
default via 172.16.0.254 proto static
172.16.0.0/24 proto kernel scope link src 172.16.0.1
```
And check the DNS configuration:
```
netplan status enp6s0
```
You should see something similar to this:
```
Online state: online
DNS Addresses: 127.0.0.53 (stub)
DNS Search: netplanlab.local
lxd
● 3: enp6s0 ethernet UP (networkd: enp6s0)
MAC Address: 00:16:3e:0c:97:8a (Red Hat, Inc.)
Addresses: 172.16.0.1/24
DNS Addresses: 172.16.0.254
172.16.0.253
DNS Search: netplanlab.local
Routes: default via 172.16.0.254 (static)
172.16.0.0/24 from 172.16.0.1 (link)
2 inactive interfaces hidden. Use "--all" to show all.
```
# Matching the interface by MAC address
Sometimes you can't rely on the interface names to apply configuration to them. Changes in the system might cause a change in their names, such as when you move an interface card from a PCI slot to another.
In this exercise you will use the `match` keyword to locate the device based on its MAC address and also set a more meaningful name to the interface.
Let's assume that your second interface is connected to the Netplan ISP internet provider company and you want to identify it as such.
First identify its MAC address:
```
ip link show enp6s0
```
In the output, the MAC address is the number in front of the `link/ether` property.
```
3: enp6s0: mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000
link/ether 00:16:3e:0c:97:8a brd ff:ff:ff:ff:ff:ff
```
Use your favorite text editor to open the file `/etc/netplan/second-interface.yaml` and make the following changes:
```yaml
network:
version: 2
ethernets:
netplan-isp-interface:
match:
macaddress: 00:16:3e:0c:97:8a
set-name: netplan-isp
dhcp4: false
dhcp6: false
accept-ra: false
link-local: []
addresses:
- 172.16.0.1/24
routes:
- to: default
via: 172.16.0.254
nameservers:
search:
- netplanlab.local
addresses:
- 172.16.0.254
- 172.16.0.253
```
These are the important changes in this exercise:
```yaml
ethernets:
netplan-isp-interface:
match:
macaddress: 00:16:3e:0c:97:8a
set-name: netplan-isp
```
Note that, as you are now matching the interface by its MAC address, you are free to identify it with a different name. It makes it easier to read and find information in the YAML file.
After changing the file, apply your new configuration:
```
netplan apply
```
Now list your interfaces:
```
ip link show
```
As you can see, your interface is now called `netplan-isp`.
```
1: lo: mtu 65536 qdisc noqueue state UNKNOWN mode DEFAULT group default qlen 1000
link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00
2: enp5s0: mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000
link/ether 00:16:3e:13:ae:10 brd ff:ff:ff:ff:ff:ff
3: netplan-isp: mtu 1500 qdisc mq state UP mode DEFAULT group default qlen 1000
link/ether 00:16:3e:0c:97:8a brd ff:ff:ff:ff:ff:ff
```
# Creating a link aggregation
Let's suppose now that you need to configure your system to connect to your
ISP links via a link aggregation. On Linux you can do that with a `bond`
virtual interface.
On Netplan, an interface of type `bond` can be created inside a `bonds` mapping.
Now that the traffic will flow through the link aggregation, you will move
all the addressing configuration to the bond itself.
You can define a list of interfaces that will be attached to the bond. In our
simple scenario, we have a single one.
Use your favorite text editor to open the file `/etc/netplan/second-interface.yaml` and make the following changes:
```yaml
network:
version: 2
ethernets:
netplan-isp-interface:
dhcp4: false
dhcp6: false
match:
macaddress: 00:16:3e:0c:97:8a
set-name: netplan-isp
bonds:
isp-bond0:
interfaces:
- netplan-isp-interface
dhcp4: false
dhcp6: false
accept-ra: false
link-local: []
addresses:
- 172.16.0.1/24
routes:
- to: default
via: 172.16.0.254
nameservers:
search:
- netplanlab.local
addresses:
- 172.16.0.254
- 172.16.0.253
```
Note that you can reference the interface used in the bond by the name you
defined for it in the `ethernets` section.
Now use `netplan apply` to apply your changes
```
netplan apply
```
Now your system has a new interface called `isp-bond0`. Use the command
`ip address show isp-bond0` or `netplan status` to check its state:
```
netplan status isp-bond0
```
You should see an output similar to the one below:
```
Online state: online
DNS Addresses: 127.0.0.53 (stub)
DNS Search: lxd
netplanlab.local
● 4: isp-bond0 bond UP (networkd: isp-bond0)
MAC Address: b2:6b:19:b1:9a:86
Addresses: 172.16.0.1/24
DNS Addresses: 172.16.0.254
172.16.0.253
DNS Search: netplanlab.local
Routes: default via 172.16.0.254 (static)
172.16.0.0/24 from 172.16.0.1 (link)
3 inactive interfaces hidden. Use "--all" to show all.
```
netplan-0.106.1/doc/netplan-yaml.md 0000664 0000000 0000000 00000201560 14431205264 0017015 0 ustar 00root root 0000000 0000000 ---
title: "YAML configuration"
---
## Top-level configuration structure
The general structure of a Netplan YAML file is shown below.
```yaml
network:
version: NUMBER
renderer: STRING
bonds: MAPPING
bridges: MAPPING
ethernets: MAPPING
modems: MAPPING
tunnels: MAPPING
vlans: MAPPING
vrfs: MAPPING
wifis: MAPPING
nm-devices: MAPPING
```
- **version** (number)
> Defines what version of the configuration format is used. The only value supported is `2`. Defaults to `2` if not defined.
- **renderer** (scalar)
> Defines what network configuration tool will be used to set up your configuration. Valid values are `networkd` and `NetworkManager`. Defaults to `networkd` if not defined.
- [**bonds**](#properties-for-device-type-bonds) (mapping)
> Creates and configures link aggregation (bonding) devices.
- [**bridges**](#properties-for-device-type-bridges) (mapping)
> Creates and configures bridge devices.
- [**ethernets**](#properties-for-device-type-ethernets) (mapping)
> Configures physical Ethernet interfaces.
- [**modems**](#properties-for-device-type-modems) (mapping)
> Configures modems
- [**tunnels**](#properties-for-device-type-tunnels) (mapping)
> Creates and configures different types of virtual tunnels.
- [**vlans**](#properties-for-device-type-vlans) (mapping)
> Creates and configures VLANs.
- [**vrfs**](#properties-for-device-type-vrfs) (mapping)
> Configures Virtual Routing and Forwarding (VRF) devices.
- [**wifis**](#properties-for-device-type-wifis) (mapping)
> Configures physical Wifi interfaces as client, adhoc or access point.
- [**nm-devices**](#properties-for-device-type-nm-devices) (mapping)
> `nm-devices` are used in situations where Netplan doesn't support the connection type. The raw configuration expected by NetworkManager can be defined and will be passed as is (passthrough) to the `.nmconnection` file. Users will not normally use this type of device.
All the properties for all the device types will be described in the next sections.
## Properties for physical device types
These properties are used with physical devices such as Ethernet and Wifi network interfaces.
**Note:** Some options will not work reliably for devices matched by name only
and rendered by networkd, due to interactions with device renaming in udev.
Match devices by MAC when setting options like: `wakeonlan` or `*-offload`.
- **match** (mapping)
> This selects a subset of available physical devices by various hardware
> properties. The following configuration will then apply to all matching
> devices, as soon as they appear. *All* specified properties must match.
- **name** (scalar)
> Current interface name. Globs are supported, and the primary use case for
> matching on names, as selecting one fixed name can be more easily achieved
> with having no `match:` at all and just using the ID (see above).
> (`NetworkManager`: as of v1.14.0)
- **macaddress** (scalar)
> Device's 6-byte permanent MAC address in the form "XX:XX:XX:XX:XX:XX" or
> 20 bytes for InfiniBand devices (IPoIB). Globs are not allowed.
> This doesn't match virtual MAC addresses for veth, bridge, bond, vlan, ...
- **driver** (scalar or sequence of scalars) – sequence since **0.104**
> Kernel driver name, corresponding to the `DRIVER` udev property.
> A sequence of globs is supported, any of which must match.
> Matching on driver is *only* supported with networkd.
Examples:
- All cards on second PCI bus:
```yaml
network:
ethernets:
myinterface:
match:
name: enp2*
```
- Fixed MAC address:
```yaml
network:
ethernets:
interface0:
match:
macaddress: 11:22:33:AA:BB:FF
```
- First card of driver ``ixgbe``:
```yaml
network:
ethernets:
nic0:
match:
driver: ixgbe
name: en*s0
```
- First card with a driver matching ``bcmgenet`` or ``smsc*``:
```yaml
network:
ethernets:
nic0:
match:
driver: ["bcmgenet", "smsc*"]
name: en*
```
- **set-name** (scalar)
> When matching on unique properties such as path or MAC, or with additional
> assumptions such as "there will only ever be one wifi device", match rules
> can be written so that they only match one device. Then this property can be
> used to give that device a more specific/desirable/nicer name than the
> default from udev's ifnames. Any additional device that satisfies the match
> rules will then fail to get renamed and keep the original kernel name (and
> dmesg will show an error).
- **wakeonlan** (bool)
> Enable wake on LAN. Off by default.
- **emit-lldp** (bool) – since **0.99**
> (networkd backend only) Whether to emit LLDP packets. Off by default.
- **receive-checksum-offload** (bool) – since **0.104**
> (networkd backend only) If set to true (false), the hardware offload for
> checksumming of ingress network packets is enabled (disabled). When unset,
> the kernel's default will be used.
- **transmit-checksum-offload** (bool) – since **0.104**
> (networkd backend only) If set to true (false), the hardware offload for
> checksumming of egress network packets is enabled (disabled). When unset,
> the kernel's default will be used.
- **tcp-segmentation-offload** (bool) – since **0.104**
> (networkd backend only) If set to true (false), the TCP Segmentation
> Offload (TSO) is enabled (disabled). When unset, the kernel's default will
> be used.
- **tcp6-segmentation-offload** (bool) – since **0.104**
> (networkd backend only) If set to true (false), the TCP6 Segmentation
> Offload (tx-tcp6-segmentation) is enabled (disabled). When unset, the
> kernel's default will be used.
- **generic-segmentation-offload** (bool) – since **0.104**
> (networkd backend only) If set to true (false), the Generic Segmentation
> Offload (GSO) is enabled (disabled). When unset, the kernel's default will
> be used.
- **generic-receive-offload** (bool) – since **0.104**
> (networkd backend only) If set to true (false), the Generic Receive
> Offload (GRO) is enabled (disabled). When unset, the kernel's default will
> be used.
- **large-receive-offload** (bool) – since **0.104**
> (networkd backend only) If set to true (false), the Large Receive Offload
> (LRO) is enabled (disabled). When unset, the kernel's default will
> be used.
- **openvswitch** (mapping) – since **0.100**
> This provides additional configuration for the openvswitch network device.
> If Open vSwitch is not available on the system, netplan treats the presence
> of `openvswitch` configuration as an error.
>
> Any supported network device that is declared with the `openvswitch`
> mapping (or any bond/bridge that includes an interface with an openvswitch
> configuration) will be created in openvswitch instead of the defined
> renderer. In the case of a `vlan` definition declared the same way,
> netplan will create a fake VLAN bridge in openvswitch with the requested
> `vlan` properties.
- **external-ids** (mapping) – since **0.100**
> Passed-through directly to Open vSwitch
- **other-config** (mapping) – since **0.100**
> Passed-through directly to Open vSwitch
- **lacp** (scalar) – since **0.100**
> Valid for bond interfaces. Accepts `active`, `passive` or `off` (the
> default).
- **fail-mode** (scalar) – since **0.100**
> Valid for bridge interfaces. Accepts `secure` or `standalone` (the
> default).
- **mcast-snooping** (bool) – since **0.100**
> Valid for bridge interfaces. False by default.
- **protocols** (sequence of scalars) – since **0.100**
> Valid for bridge interfaces or the network section. List of protocols to
> be used when negotiating a connection with the controller. Accepts
> `OpenFlow10`, `OpenFlow11`, `OpenFlow12`, `OpenFlow13`, `OpenFlow14`,
> and `OpenFlow15`.
- **rstp** (bool) – since **0.100**
> Valid for bridge interfaces. False by default.
- **controller** (mapping) – since **0.100**
> Valid for bridge interfaces. Specify an external OpenFlow controller.
- **addresses** (sequence of scalars)
> Set the list of addresses to use for the controller targets. The
> syntax of these addresses is as defined in ovs-vsctl(8). Example:
> addresses: `[tcp:127.0.0.1:6653, "ssl:[fe80::1234%eth0]:6653"]`
- **connection-mode** (scalar)
> Set the connection mode for the controller. Supported options are
> `in-band` and `out-of-band`. The default is `in-band`.
- **ports** (sequence of sequence of scalars) – since **0.100**
> Open vSwitch patch ports. Each port is declared as a pair of names
> which can be referenced as interfaces in dependent virtual devices
> (bonds, bridges).
Example:
```yaml
openvswitch:
ports:
- [patch0-1, patch1-0]
```
- **ssl** (mapping) – since **0.100**
> Valid for global `openvswitch` settings. Options for configuring SSL
> server endpoint for the switch.
- **ca-cert** (scalar)
> Path to a file containing the CA certificate to be used.
- **certificate** (scalar)
> Path to a file containing the server certificate.
- **private-key** (scalar)
> Path to a file containing the private key for the server.
## Properties for all device types
- **renderer** (scalar)
> Use the given networking backend for this definition. Currently supported
> are `networkd` and `NetworkManager`. This property can be specified globally
> in `network:`, for a device type (in e. g. `ethernets:`) or
> for a particular device definition. Default is `networkd`.
>
> (Since 0.99) The `renderer` property has one additional acceptable value for
> vlan objects (i. e. defined in `vlans:`): `sriov`. If a vlan is defined with
> the `sriov` renderer for an SR-IOV Virtual Function interface, this causes
> netplan to set up a hardware VLAN filter for it. There can be only one
> defined per VF.
- **dhcp4** (bool)
> Enable DHCP for IPv4. Off by default.
- **dhcp6** (bool)
> Enable DHCP for IPv6. Off by default. This covers both stateless DHCP -
> where the DHCP server supplies information like DNS nameservers but not the
> IP address - and stateful DHCP, where the server provides both the address
> and the other information.
>
> If you are in an IPv6-only environment with completely stateless
> auto-configuration (SLAAC with RDNSS), this option can be set to cause the
> interface to be brought up. (Setting accept-ra alone is not sufficient.)
> Auto-configuration will still honor the contents of the router
> advertisement and only use DHCP if requested in the RA.
>
> Note that **`rdnssd`**(8) is required to use RDNSS with networkd. No extra
> software is required for NetworkManager.
- **ipv6-mtu** (scalar) – since **0.98**
> Set the IPv6 MTU (only supported with `networkd` backend). Note
> that needing to set this is an unusual requirement.
>
> **Requires feature: ipv6-mtu**
- **ipv6-privacy** (bool)
> Enable IPv6 Privacy Extensions (RFC 4941) for the specified interface, and
> prefer temporary addresses. Defaults to false - no privacy extensions. There
> is currently no way to have a private address but prefer the public address.
- **link-local** (sequence of scalars)
> Configure the link-local addresses to bring up. Valid options are 'ipv4'
> and 'ipv6', which respectively allow enabling IPv4 and IPv6 link local
> addressing. If this field is not defined, the default is to enable only
> IPv6 link-local addresses. If the field is defined but configured as an
> empty set, IPv6 link-local addresses are disabled as well as IPv4 link-
> local addresses.
>
> This feature enables or disables link-local addresses for a protocol, but
> the actual implementation differs per backend. On networkd, this directly
> changes the behavior and may add an extra address on an interface. When
> using the NetworkManager backend, enabling link-local has no effect if the
> interface also has DHCP enabled.
Examples:
- Enable only IPv4 link-local: `link-local: [ ipv4 ]`
- Enable all link-local addresses: `link-local: [ ipv4, ipv6 ]`
- Disable all link-local addresses: `link-local: [ ]`
- **ignore-carrier** (bool) – since **0.104**
> (networkd backend only) Allow the specified interface to be configured even
> if it has no carrier.
- **critical** (bool)
> Designate the connection as "critical to the system", meaning that special
> care will be taken by to not release the assigned IP when the daemon is
> restarted. (not recognized by NetworkManager)
- **dhcp-identifier** (scalar)
> (networkd backend only) Sets the source of DHCPv4 client identifier. If
> `mac` is specified, the MAC address of the link is used. If this option is
> omitted, or if `duid` is specified, networkd will generate an
> RFC4361-compliant client identifier for the interface by combining the
> link's IAID and DUID.
- **dhcp4-overrides** (mapping)
> (networkd backend only) Overrides default DHCP behavior; see the
> `DHCP Overrides` section below.
- **dhcp6-overrides** (mapping)
> (networkd backend only) Overrides default DHCP behavior; see the
> `DHCP Overrides` section below.
- **accept-ra** (bool)
> Accept Router Advertisement that would have the kernel configure IPv6 by
> itself. When enabled, accept Router Advertisements. When disabled, do not
> respond to Router Advertisements. If unset use the host kernel default
> setting.
- **addresses** (sequence of scalars and mappings)
> Add static addresses to the interface in addition to the ones received
> through DHCP or RA. Each sequence entry is in CIDR notation, i. e. of the
> form `addr/prefixlen`. `addr` is an IPv4 or IPv6 address as recognized
> by **`inet_pton`**(3) and `prefixlen` the number of bits of the subnet.
>
> For virtual devices (bridges, bonds, vlan) if there is no address
> configured and DHCP is disabled, the interface may still be brought online,
> but will not be addressable from the network.
>
> In addition to the addresses themselves one can specify configuration
> parameters as mappings. Current supported options are:
- **lifetime** (scalar) – since **0.100**
> Default: ``forever``. This can be ``forever`` or ``0`` and corresponds
> to the ``PreferredLifetime`` option in ``systemd-networkd``'s Address
> section. Currently supported on the ``networkd`` backend only.
- **label** (scalar) – since **0.100**
> An IP address label, equivalent to the ``ip address label``
> command. Currently supported on the ``networkd`` backend only.
Examples:
- Simple: ``addresses: [192.168.14.2/24, "2001:1::1/64"]``
- Advanced:
```yaml
network:
ethernets:
eth0:
addresses:
- "10.0.0.15/24":
lifetime: 0
label: "maas"
- "2001:1::1/64"
```
- **ipv6-address-generation** (scalar) – since **0.99**
> Configure method for creating the address for use with RFC4862 IPv6
> Stateless Address Auto-configuration (only supported with `NetworkManager`
> backend). Possible values are `eui64` or `stable-privacy`.
- **ipv6-address-token** (scalar) – since **0.100**
> Define an IPv6 address token for creating a static interface identifier for
> IPv6 Stateless Address Auto-configuration. This is mutually exclusive with
> `ipv6-address-generation`.
- **gateway4**, **gateway6** (scalar)
> Deprecated, see `Default routes`.
> Set default gateway for IPv4/6, for manual address configuration. This
> requires setting `addresses` too. Gateway IPs must be in a form
> recognized by **`inet_pton`**(3). There should only be a single gateway
> per IP address family set in your global config, to make it unambiguous.
> If you need multiple default routes, please define them via
> `routing-policy`.
Examples
- IPv4: `gateway4: 172.16.0.1`
- IPv6: `gateway6: "2001:4::1"`
- **nameservers** (mapping)
> Set DNS servers and search domains, for manual address configuration. There
> are two supported fields: `addresses:` is a list of IPv4 or IPv6 addresses
> similar to `gateway*`, and `search:` is a list of search domains.
Example:
```yaml
network:
ethernets:
id0:
[...]
nameservers:
search: [lab, home]
addresses: [8.8.8.8, "FEDC::1"]
```
- **macaddress** (scalar)
> Set the device's MAC address. The MAC address must be in the form
> "XX:XX:XX:XX:XX:XX".
>
> **Note:** This will not work reliably for devices matched by name
> only and rendered by networkd, due to interactions with device
> renaming in udev. Match devices by MAC when setting MAC addresses.
Example:
```yaml
network:
ethernets:
id0:
match:
macaddress: 52:54:00:6b:3c:58
[...]
macaddress: 52:54:00:6b:3c:59
```
- **mtu** (scalar)
> Set the Maximum Transmission Unit for the interface. The default is 1500.
> Valid values depend on your network interface.
>
> **Note:** This will not work reliably for devices matched by name
> only and rendered by networkd, due to interactions with device
> renaming in udev. Match devices by MAC when setting MTU.
- **optional** (bool)
> An optional device is not required for booting. Normally, networkd will
> wait some time for device to become configured before proceeding with
> booting. However, if a device is marked as optional, networkd will not wait
> for it. This is *only* supported by networkd, and the default is false.
Example:
```yaml
network:
ethernets:
eth7:
# this is plugged into a test network that is often
# down - don't wait for it to come up during boot.
dhcp4: true
optional: true
```
- **optional-addresses** (sequence of scalars)
> Specify types of addresses that are not required for a device to be
> considered online. This changes the behavior of backends at boot time to
> avoid waiting for addresses that are marked optional, and thus consider
> the interface as "usable" sooner. This does not disable these addresses,
> which will be brought up anyway.
Example:
```yaml
network:
ethernets:
eth7:
dhcp4: true
dhcp6: true
optional-addresses: [ ipv4-ll, dhcp6 ]
```
- **activation-mode** (scalar) – since **0.103**
> Allows specifying the management policy of the selected interface. By
> default, netplan brings up any configured interface if possible. Using the
> `activation-mode` setting users can override that behavior by either
> specifying `manual`, to hand over control over the interface state to the
> administrator or (for networkd backend *only*) `off` to force the link
> in a down state at all times. Any interface with `activation-mode`
> defined is implicitly considered `optional`.
> Supported officially as of `networkd` v248+.
Example:
```yaml
network:
ethernets:
eth1:
# this interface will not be put into an UP state automatically
dhcp4: true
activation-mode: manual
```
- **routes** (sequence of mappings)
> Configure static routing for the device; see the `Routing` section below.
- **routing-policy** (sequence of mappings)
> Configure policy routing for the device; see the `Routing` section below.
- **neigh-suppress** (scalar) – since **0.105**
> Takes a boolean. Configures whether ARP and ND neighbor suppression is
> enabled for this port. When unset, the kernel's default will be used.
## DHCP Overrides
Several DHCP behavior overrides are available. Most currently only have any
effect when using the `networkd` backend, with the exception of `use-routes`
and `route-metric`.
Overrides only have an effect if the corresponding `dhcp4` or `dhcp6` is
set to `true`.
If both `dhcp4` and `dhcp6` are `true`, the `networkd` backend requires
that `dhcp4-overrides` and `dhcp6-overrides` contain the same keys and
values. If the values do not match, an error will be shown and the network
configuration will not be applied.
When using the NetworkManager backend, different values may be specified for
`dhcp4-overrides` and `dhcp6-overrides`, and will be applied to the DHCP
client processes as specified in the netplan YAML.
- **dhcp4-overrides**, **dhcp6-overrides** (mapping)
> The `dhcp4-overrides` and `dhcp6-override`` mappings override the
> default DHCP behavior.
- **use-dns** (bool)
> Default: `true`. When `true`, the DNS servers received from the
> DHCP server will be used and take precedence over any statically
> configured ones. Currently only has an effect on the `networkd`
> backend.
- **use-ntp** (bool)
> Default: `true`. When `true`, the NTP servers received from the
> DHCP server will be used by systemd-timesyncd and take precedence
> over any statically configured ones. Currently only has an effect on
> the `networkd` backend.
- **send-hostname** (bool)
> Default: `true`. When `true`, the machine's hostname will be sent
> to the DHCP server. Currently only has an effect on the `networkd`
> backend.
- **use-hostname** (bool)
> Default: `true`. When `true`, the hostname received from the DHCP
> server will be set as the transient hostname of the system. Currently
> only has an effect on the `networkd` backend.
- **use-mtu** (bool)
> Default: `true`. When `true`, the MTU received from the DHCP
> server will be set as the MTU of the network interface. When `false`,
> the MTU advertised by the DHCP server will be ignored. Currently only
> has an effect on the `networkd` backend.
- **hostname** (scalar)
> Use this value for the hostname which is sent to the DHCP server,
> instead of machine's hostname. Currently only has an effect on the
> `networkd` backend.
- **use-routes** (bool)
> Default: `true`. When `true`, the routes received from the DHCP
> server will be installed in the routing table normally. When set to
> `false`, routes from the DHCP server will be ignored: in this case,
> the user is responsible for adding static routes if necessary for
> correct network operation. This allows users to avoid installing a
> default gateway for interfaces configured via DHCP. Available for
> both the `networkd` and `NetworkManager` backends.
- **route-metric** (scalar)
> Use this value for default metric for automatically-added routes.
> Use this to prioritize routes for devices by setting a lower metric
> on a preferred interface. Available for both the `networkd` and
> `NetworkManager` backends.
- **use-domains** (scalar) – since **0.98**
> Takes a boolean, or the special value "route". When true, the domain
> name received from the DHCP server will be used as DNS search domain
> over this link, similar to the effect of the Domains= setting. If set
> to "route", the domain name received from the DHCP server will be
> used for routing DNS queries only, but not for searching, similar to
> the effect of the Domains= setting when the argument is prefixed with
> "~".
>
> **Requires feature: dhcp-use-domains**
## Routing
Complex routing is possible with netplan. Standard static routes as well
as policy routing using routing tables are supported via the `networkd`
backend.
These options are available for all types of interfaces.
### Default routes
The most common need for routing concerns the definition of default routes to
reach the wider Internet. Those default routes can only defined once per IP
family and routing table. A typical example would look like the following:
```yaml
network:
ethernets:
eth0:
[...]
routes:
- to: default # could be 0.0.0.0/0 optionally
via: 10.0.0.1
metric: 100
on-link: true
- to: default # could be ::/0 optionally
via: cf02:de:ad:be:ef::2
eth1:
[...]
routes:
- to: default
via: 172.134.67.1
metric: 100
on-link: true
# Not on the main routing table,
# does not conflict with the eth0 default route
table: 76
```
- **routes** (mapping)
> The `routes` block defines standard static routes for an interface.
> At least `to` must be specified. If type is `local` or `nat` a
> default scope of `host` is assumed.
> If type is `unicast` and no gateway (`via`) is given or type is
> `broadcast`, `multicast` or `anycast` a default scope of `link`
> is assumed. Otherwise, a ``global`` scope is the default setting.
>
> For `from`, `to`, and `via`, both IPv4 and IPv6 addresses are
> recognized, and must be in the form `addr/prefixlen` or `addr`.
- **from** (scalar)
> Set a source IP address for traffic going through the route.
> (`NetworkManager`: as of v1.8.0)
- **to** (scalar)
> Destination address for the route.
- **via** (scalar)
> Address to the gateway to use for this route.
- **on-link** (bool)
> When set to "true", specifies that the route is directly connected
> to the interface.
> (`NetworkManager`: as of v1.12.0 for IPv4 and v1.18.0 for IPv6)
- **metric** (scalar)
> The relative priority of the route. Must be a positive integer value.
- **type** (scalar)
> The type of route. Valid options are "unicast" (default), "anycast",
> "blackhole", "broadcast", "local", "multicast", "nat", "prohibit",
> "throw", "unreachable" or "xresolve".
- **scope** (scalar)
> The route scope, how wide-ranging it is to the network. Possible
> values are "global", "link", or "host". Applies to IPv4 only.
- **table** (scalar)
> The table number to use for the route. In some scenarios, it may be
> useful to set routes in a separate routing table. It may also be used
> to refer to routing policy rules which also accept a `table`
> parameter. Allowed values are positive integers starting from 1.
> Some values are already in use to refer to specific routing tables:
> see `/etc/iproute2/rt_tables`.
> (`NetworkManager`: as of v1.10.0)
- **mtu** (scalar) – since **0.101**
> The MTU to be used for the route, in bytes. Must be a positive integer
> value.
- **congestion-window** (scalar) – since **0.102**
> The congestion window to be used for the route, represented by number
> of segments. Must be a positive integer value.
- **advertised-receive-window** (scalar) – since **0.102**
> The receive window to be advertised for the route, represented by
> number of segments. Must be a positive integer value.
- **routing-policy** (mapping)
> The `routing-policy` block defines extra routing policy for a network,
> where traffic may be handled specially based on the source IP, firewall
> marking, etc.
>
> For `from`, `to`, both IPv4 and IPv6 addresses are recognized, and
> must be in the form `addr/prefixlen` or `addr`.
- **from** (scalar)
> Set a source IP address to match traffic for this policy rule.
- **to** (scalar)
> Match on traffic going to the specified destination.
- **table** (scalar)
> The table number to match for the route. In some scenarios, it may be
> useful to set routes in a separate routing table. It may also be used
> to refer to routes which also accept a `table` parameter.
> Allowed values are positive integers starting from 1.
> Some values are already in use to refer to specific routing tables:
> see `/etc/iproute2/rt_tables`.
- **priority** (scalar)
> Specify a priority for the routing policy rule, to influence the order
> in which routing rules are processed. A higher number means lower
> priority: rules are processed in order by increasing priority number.
- **mark** (scalar)
> Have this routing policy rule match on traffic that has been marked
> by the iptables firewall with this value. Allowed values are positive
> integers starting from 1.
- **type-of-service** (scalar)
> Match this policy rule based on the type of service number applied to
> the traffic.
## Authentication
Netplan supports advanced authentication settings for ethernet and wifi
interfaces, as well as individual wifi networks, by means of the `auth` block.
- **auth** (mapping)
> Specifies authentication settings for a device of type `ethernets:`, or
> an `access-points:` entry on a `wifis:` device.
>
> The `auth` block supports the following properties:
- **key-management** (scalar)
> The supported key management modes are `none` (no key management);
> `psk` (WPA with pre-shared key, common for home wifi); `eap` (WPA
> with EAP, common for enterprise wifi); and `802.1x` (used primarily
> for wired Ethernet connections).
- **password** (scalar)
> The password string for EAP, or the pre-shared key for WPA-PSK.
The following properties can be used if `key-management` is `eap`
or `802.1x`:
- **method** (scalar)
> The EAP method to use. The supported EAP methods are `tls` (TLS),
> `peap` (Protected EAP), and `ttls` (Tunneled TLS).
- **identity** (scalar)
> The identity to use for EAP.
- **anonymous-identity** (scalar)
> The identity to pass over the unencrypted channel if the chosen EAP
> method supports passing a different tunnelled identity.
- **ca-certificate** (scalar)
> Path to a file with one or more trusted certificate authority (CA)
> certificates.
- **client-certificate** (scalar)
> Path to a file containing the certificate to be used by the client
> during authentication.
- **client-key** (scalar)
> Path to a file containing the private key corresponding to
> `client-certificate`.
- **client-key-password** (scalar)
> Password to use to decrypt the private key specified in
> `client-key` if it is encrypted.
- **phase2-auth** (scalar) – since **0.99**
> Phase 2 authentication mechanism.
## Properties for device type `ethernets:`
**Status**: Optional.
**Purpose**: Use the `ethernets` key to configure Ethernet interfaces.
**Structure**: The key consists of a mapping of Ethernet interface IDs. Each
`ethernet` has a number of configuration options. You don't need to define each
interface by their name inside the `ethernets` mapping. You can use any ID that
describes the interface and match the actual network card using the `match` key.
The general configuration structure for Ethernets is shown below.
```yaml
network:
ethernets:
device-id:
...
```
`device-id` is the interface identifier. If you use the interface name as the ID, Netplan will match that interface.
Consider the example below. In this case, an interface called `eth0` will be configured with DHCP.
```yaml
network:
ethernets:
eth0:
dhcp4: true
```
The `device-id` can be any descriptive name your find meaningful. Although, if it doesn't match a real interface name, you must use the property `match` to identify the device you want to configure.
The example below defines an Ethernet connection called `isp-interface` (supposedly an external interface connected to the Internet Service Provider) and uses `match` to apply the configuration to the physical device with MAC address `aa:bb:cc:00:11:22`.
```yaml
network:
ethernets:
isp-interface:
match:
macaddress: aa:bb:cc:00:11:22
dhcp4: true
```
Ethernet device definitions, beyond common ones described above, also support
some additional properties that can be used for SR-IOV devices.
- **link** (scalar) – since **0.99**
> (SR-IOV devices only) The `link` property declares the device as a
> Virtual Function of the selected Physical Function device, as identified
> by the given netplan id.
Example:
```yaml
network:
ethernets:
enp1: {...}
enp1s16f1:
link: enp1
```
- **virtual-function-count** (scalar) – since **0.99**
> (SR-IOV devices only) In certain special cases VFs might need to be
> configured outside of netplan. For such configurations
> `virtual-function-count` can be optionally used to set an explicit number of
> Virtual Functions for the given Physical Function. If unset, the default is
> to create only as many VFs as are defined in the netplan configuration. This
> should be used for special cases only.
>
> **Requires feature: sriov**
- **embedded-switch-mode** (scalar) – since **0.104**
> (SR-IOV devices only) Change the operational mode of the embedded switch
> of a supported SmartNIC PCI device (e.g. Mellanox ConnectX-5). Possible
> values are `switchdev` or `legacy`, if unspecified the vendor's
> default configuration is used.
>
> **Requires feature: eswitch-mode**
- **delay-virtual-functions-rebind** (bool) – since **0.104**
> (SR-IOV devices only) Delay rebinding of SR-IOV virtual functions to its
> driver after changing the embedded-switch-mode setting to a later stage.
> Can be enabled when bonding/VF LAG is in use. Defaults to `false`.
>
> **Requires feature: eswitch-mode**
- **infiniband-mode** (scalar) – since **0.105**
> (InfiniBand devices only) Change the operational mode of a IPoIB device.
> Possible values are `datagram` or `connected`. If unspecified the
> kernel's default configuration is used.
>
> **Requires feature: infiniband**
## Properties for device type `modems:`
**Status**: Optional.
**Purpose**: Use the `modems` key to configure Modem interfaces. GSM/CDMA modem
configuration is only supported for the `NetworkManager` backend.
`systemd-networkd` does not support modems.
**Structure**: The key consists of a mapping of Modem IDs. Each `modem` has a
number of configuration options. The general configuration structure for Modems
is shown below.
```yaml
network:
version: 2
renderer: NetworkManager
modems:
cdc-wdm1:
mtu: 1600
apn: ISP.CINGULAR
username: ISP@CINGULARGPRS.COM
password: CINGULAR1
number: "*99#"
network-id: 24005
device-id: da812de91eec16620b06cd0ca5cbc7ea25245222
pin: 2345
sim-id: 89148000000060671234
sim-operator-id: 310260
```
**Requires feature: modems**
- **apn** (scalar) – since **0.99**
> Set the carrier APN (Access Point Name). This can be omitted if
> `auto-config` is enabled.
- **auto-config** (bool) – since **0.99**
> Specify whether to try and auto-configure the modem by doing a lookup of
> the carrier against the Mobile Broadband Provider database. This may not
> work for all carriers.
- **device-id** (scalar) – since **0.99**
> Specify the device ID (as given by the WWAN management service) of the
> modem to match. This can be found using `mmcli`.
- **network-id** (scalar) – since **0.99**
> Specify the Network ID (GSM LAI format). If this is specified, the device
> will not roam networks.
- **number** (scalar) – since **0.99**
> The number to dial to establish the connection to the mobile broadband
> network. (Deprecated for GSM)
- **password** (scalar) – since **0.99**
> Specify the password used to authenticate with the carrier network. This
> can be omitted if `auto-config` is enabled.
- **pin** (scalar) – since **0.99**
> Specify the SIM PIN to allow it to operate if a PIN is set.
- **sim-id** (scalar) – since **0.99**
> Specify the SIM unique identifier (as given by the WWAN management service)
> which this connection applies to. If given, the connection will apply to
> any device also allowed by `device-id` which contains a SIM card matching
> the given identifier.
- **sim-operator-id** (scalar) – since **0.99**
> Specify the MCC/MNC string (such as "310260" or "21601") which identifies
> the carrier that this connection should apply to. If given, the connection
> will apply to any device also allowed by `device-id` and `sim-id`
> which contains a SIM card provisioned by the given operator.
- **username** (scalar) – since **0.99**
> Specify the username used to authenticate with the carrier network. This
> can be omitted if `auto-config` is enabled.
## Properties for device type `wifis:`
**Status**: Optional.
**Purpose**: Use the `wifis` key to configure WiFi access points.
**Structure**: The key consists of a mapping of WiFi IDs. Each `wifi` has a
number of configuration options. The general configuration structure for WiFis
is shown below.
```yaml
network:
version: 2
wifis:
wlp0s1:
access-points:
"network_ssid_name":
password: "**********"
```
Note that `systemd-networkd` does not natively support wifi, so you need
wpasupplicant installed if you let the `networkd` renderer handle wifi.
- **access-points** (mapping)
> This provides pre-configured connections to NetworkManager. Note that
> users can of course select other access points/SSIDs. The keys of the
> mapping are the SSIDs, and the values are mappings with the following
> supported properties:
- **password** (scalar)
> Enable WPA/WPA2 authentication and set the passphrase for it. If neither
> this nor an `auth` block are given, the network is assumed to be
> open. The setting
> ```yaml
> password: "S3kr1t"
> ```
> is equivalent to
> ```yaml
> auth:
> key-management: psk
> password: "S3kr1t"
> ```
- **mode** (scalar)
> Possible access point modes are `infrastructure` (the default),
> `ap` (create an access point to which other devices can connect),
> and `adhoc` (peer to peer networks without a central access point).
> `ap` is only supported with NetworkManager.
- **bssid** (scalar) – since **0.99**
> If specified, directs the device to only associate with the given
> access point.
- **band** (scalar) – since **0.99**
> Possible bands are `5GHz` (for 5GHz 802.11a) and `2.4GHz`
> (for 2.4GHz 802.11), do not restrict the 802.11 frequency band of the
> network if unset (the default).
- **channel** (scalar) – since **0.99**
> Wireless channel to use for the Wi-Fi connection. Because channel
> numbers overlap between bands, this property takes effect only if
> the `band` property is also set.
- **hidden** (bool) – since **0.100**
> Set to `true` to change the SSID scan technique for connecting to
> hidden WiFi networks. Note this may have slower performance compared
> to `false` (the default) when connecting to publicly broadcast
> SSIDs.
- **wakeonwlan** (sequence of scalars) – since **0.99**
> This enables WakeOnWLan on supported devices. Not all drivers support all
> options. May be any combination of `any`, `disconnect`, `magic_pkt`,
> `gtk_rekey_failure`, `eap_identity_req`, `four_way_handshake`,
> `rfkill_release` or `tcp` (NetworkManager only). Or the exclusive
> `default` flag (the default).
- **regulatory-domain** (scalar) – since **0.105**
> This can be used to define the radio's regulatory domain, to make use of
> additional WiFi channels outside the "world domain". Takes an ISO /
> IEC 3166 country code (like `GB`) or `00` to reset to the "world domain".
> See [wireless-regdb](https://git.kernel.org/pub/scm/linux/kernel/git/sforshee/wireless-regdb.git/tree/db.txt)
> for available values.
>
> **Requires dependency: iw**, if it is to be used outside the `networkd`
> (wpa_supplicant) backend.
## Properties for device type `bridges:`
**Status**: Optional.
**Purpose**: Use the `bridges` key to create Bridge interfaces.
**Structure**: The key consists of a mapping of Bridge interface names. Each
`bridge` has an optional list of interfaces that will be bridged together. The
interfaces listed in the `interfaces` key (`enp5s0` and `enp5s1` below) must
also be defined in your Netplan configuration. The general configuration
structure for Bridges is shown below.
```yaml
network:
bridges:
br0:
interfaces:
- enp5s0
- enp5s1
dhcp4: true
...
```
When applied, a virtual interface of type bridge called `br0` will be created in the system.
The specific settings for bridges are defined below.
- **interfaces** (sequence of scalars)
> All devices matching this ID list will be added to the bridge. This may
> be an empty list, in which case the bridge will be brought online with
> no member interfaces.
Example:
```yaml
network:
ethernets:
switchports:
match: {name: "enp2*"}
[...]
bridges:
br0:
interfaces: [switchports]
```
- **parameters** (mapping)
> Customization parameters for special bridging options. Time intervals
> may need to be expressed as a number of seconds or milliseconds: the
> default value type is specified below. If necessary, time intervals can
> be qualified using a time suffix (such as "s" for seconds, "ms" for
> milliseconds) to allow for more control over its behavior.
- **ageing-time**, **aging-time** (scalar)
> Set the period of time to keep a MAC address in the forwarding
> database after a packet is received. This maps to the AgeingTimeSec=
> property when the networkd renderer is used. If no time suffix is
> specified, the value will be interpreted as seconds.
- **priority** (scalar)
> Set the priority value for the bridge. This value should be a
> number between `0` and `65535`. Lower values mean higher
> priority. The bridge with the higher priority will be elected as
> the root bridge.
- **port-priority** (mapping)
> Set the port priority per interface. The priority value is
> a number between `0` and `63`. This metric is used in the
> designated port and root port selection algorithms.
Example:
```yaml
network:
ethernets:
eth0:
dhcp4: false
eth1:
dhcp4: false
bridges:
br0:
interfaces: [eth0, eth1]
parameters:
port-priority:
eth0: 10
eth1: 20
```
- **forward-delay** (scalar)
> Specify the period of time the bridge will remain in Listening and
> Learning states before getting to the Forwarding state. This field
> maps to the ForwardDelaySec= property for the networkd renderer.
> If no time suffix is specified, the value will be interpreted as
> seconds.
- **hello-time** (scalar)
> Specify the interval between two hello packets being sent out from
> the root and designated bridges. Hello packets communicate
> information about the network topology. When the networkd renderer
> is used, this maps to the HelloTimeSec= property. If no time suffix
> is specified, the value will be interpreted as seconds.
- **max-age** (scalar)
> Set the maximum age of a hello packet. If the last hello packet is
> older than that value, the bridge will attempt to become the root
> bridge. This maps to the MaxAgeSec= property when the networkd
> renderer is used. If no time suffix is specified, the value will be
> interpreted as seconds.
- **path-cost** (mapping)
> Set the per-interface cost of a path on the bridge. Faster interfaces
> should have a lower cost. This allows a finer control on the network
> topology so that the fastest paths are available whenever possible.
Example:
```yaml
network:
ethernets:
eth0:
dhcp4: false
eth1:
dhcp4: false
bridges:
br0:
interfaces: [eth0, eth1]
parameters:
path-cost:
eth0: 100
eth1: 200
```
- **stp** (bool)
> Define whether the bridge should use Spanning Tree Protocol. The
> default value is "true", which means that Spanning Tree should be
> used.
## Properties for device type `bonds:`
**Status**: Optional.
**Purpose**: Use the `bonds` key to create Bond (Link Aggregation) interfaces.
**Structure**: The key consists of a mapping of Bond interface names. Each
`bond` has an optional list of interfaces that will be part of the aggregation.
The interfaces listed in the `interfaces` key must also be defined in your
Netplan configuration. The general configuration structure for Bonds is shown
below.
```yaml
network:
bonds:
bond0:
interfaces:
- enp5s0
- enp5s1
- enp5s2
mode: active-backup
...
```
When applied, a virtual interface of type bond called `bond0` will be created in the system.
The specific settings for bonds are defined below.
- **interfaces** (sequence of scalars)
> All devices matching this ID list will be added to the bond.
Example:
```yaml
network:
ethernets:
switchports:
match: {name: "enp2*"}
[...]
bonds:
bond0:
interfaces: [switchports]
```
- **parameters** (mapping)
> Customization parameters for special bonding options. Time intervals
> may need to be expressed as a number of seconds or milliseconds: the
> default value type is specified below. If necessary, time intervals can
> be qualified using a time suffix (such as "s" for seconds, "ms" for
> milliseconds) to allow for more control over its behavior.
- **mode** (scalar)
> Set the bonding mode used for the interfaces. The default is
> `balance-rr` (round robin). Possible values are `balance-rr`,
> `active-backup`, `balance-xor`, `broadcast`, `802.3ad`,
> `balance-tlb`, and `balance-alb`.
> For Open vSwitch `active-backup` and the additional modes
> `balance-tcp` and `balance-slb` are supported.
- **lacp-rate** (scalar)
> Set the rate at which LACPDUs are transmitted. This is only useful
> in 802.3ad mode. Possible values are `slow` (30 seconds, default),
> and `fast` (every second).
- **mii-monitor-interval** (scalar)
> Specifies the interval for MII monitoring (verifying if an interface
> of the bond has carrier). The default is `0`; which disables MII
> monitoring. This is equivalent to the MIIMonitorSec= field for the
> networkd backend. If no time suffix is specified, the value will be
> interpreted as milliseconds.
- **min-links** (scalar)
> The minimum number of links up in a bond to consider the bond
> interface to be up.
- **transmit-hash-policy** (scalar)
> Specifies the transmit hash policy for the selection of ports. This
> is only useful in balance-xor, 802.3ad and balance-tlb modes.
> Possible values are `layer2`, `layer3+4`, `layer2+3`,
> `encap2+3`, and `encap3+4`.
- **ad-select** (scalar)
> Set the aggregation selection mode. Possible values are `stable`,
> `bandwidth`, and `count`. This option is only used in 802.3ad
> mode.
- **all-members-active** (bool) – since **0.106**
> If the bond should drop duplicate frames received on inactive ports,
> set this option to `false`. If they should be delivered, set this
> option to `true`. The default value is false, and is the desirable
> behavior in most situations.
>
> Alias: **all-slaves-active**
- **arp-interval** (scalar)
> Set the interval value for how frequently ARP link monitoring should
> happen. The default value is `0`, which disables ARP monitoring.
> For the networkd backend, this maps to the ARPIntervalSec= property.
> If no time suffix is specified, the value will be interpreted as
> milliseconds.
- **arp-ip-targets** (sequence of scalars)
> IPs of other hosts on the link which should be sent ARP requests in
> order to validate that a port is up. This option is only used when
> `arp-interval` is set to a value other than `0`. At least one IP
> address must be given for ARP link monitoring to function. Only IPv4
> addresses are supported. You can specify up to 16 IP addresses. The
> default value is an empty list.
- **arp-validate** (scalar)
> Configure how ARP replies are to be validated when using ARP link
> monitoring. Possible values are `none`, `active`, `backup`,
> and `all`.
- **arp-all-targets** (scalar)
> Specify whether to use any ARP IP target being up as sufficient for
> a port to be considered up; or if all the targets must be up. This
> is only used for `active-backup` mode when `arp-validate` is
> enabled. Possible values are `any` and `all`.
- **up-delay** (scalar)
> Specify the delay before enabling a link once the link is physically
> up. The default value is `0`. This maps to the UpDelaySec= property
> for the networkd renderer. This option is only valid for the miimon
> link monitor. If no time suffix is specified, the value will be
> interpreted as milliseconds.
- **down-delay** (scalar)
> Specify the delay before disabling a link once the link has been
> lost. The default value is `0`. This maps to the DownDelaySec=
> property for the networkd renderer. This option is only valid for the
> miimon link monitor. If no time suffix is specified, the value will
> be interpreted as milliseconds.
- **fail-over-mac-policy** (scalar)
> Set whether to set all ports to the same MAC address when adding
> them to the bond, or how else the system should handle MAC addresses.
> The possible values are `none`, `active`, and `follow`.
- **gratuitous-arp** (scalar)
> Specify how many ARP packets to send after failover. Once a link is
> up on a new port, a notification is sent and possibly repeated if
> this value is set to a number greater than `1`. The default value
> is `1` and valid values are between `1` and `255`. This only
> affects `active-backup` mode.
>
> For historical reasons, the misspelling `gratuitious-arp` is also
> accepted and has the same function.
- **packets-per-member** (scalar) – since **0.106**
> In `balance-rr` mode, specifies the number of packets to transmit
> on a port before switching to the next. When this value is set to
> `0`, ports are chosen at random. Allowable values are between
> `0` and `65535`. The default value is `1`. This setting is
> only used in `balance-rr` mode.
>
> Alias: **packets-per-slave**
- **primary-reselect-policy** (scalar)
> Set the reselection policy for the primary port. On failure of the
> active port, the system will use this policy to decide how the new
> active port will be chosen and how recovery will be handled. The
> possible values are `always`, `better`, and `failure`.
- **resend-igmp** (scalar)
> In modes `balance-rr`, `active-backup`, `balance-tlb` and
> `balance-alb`, a failover can switch IGMP traffic from one
> port to another.
>
> This parameter specifies how many IGMP membership reports
> are issued on a failover event. Values range from 0 to 255. 0
> disables sending membership reports. Otherwise, the first
> membership report is sent on failover and subsequent reports
> are sent at 200ms intervals.
- **learn-packet-interval** (scalar)
> Specify the interval between sending learning packets to
> each port. The value range is between `1` and `0x7fffffff`.
> The default value is `1`. This option only affects `balance-tlb`
> and `balance-alb` modes. Using the networkd renderer, this field
> maps to the LearnPacketIntervalSec= property. If no time suffix is
> specified, the value will be interpreted as seconds.
- **primary** (scalar)
> Specify a device to be used as a primary port, or preferred device
> to use as a port for the bond (i.e. the preferred device to send
> data through), whenever it is available. This only affects
> `active-backup`, `balance-alb`, and `balance-tlb` modes.
## Properties for device type `tunnels:`
**Status**: Optional.
**Purpose**: Use the `tunnels` key to create virtual tunnel interfaces.
**Structure**: The key consists of a mapping of tunnel interface names. Each
`tunnel` requires the identification of the tunnel mode (see the section `mode`
below for the list of supported modes). The general configuration structure for
Tunnels is shown below.
```yaml
network:
tunnels:
tunnel0:
mode: SCALAR
...
```
When applied, a virtual interface called `tunnel0` will be created in the system. Its operation mode is defined by the property `mode`.
Tunnels allow traffic to pass as if it was between systems on the same local
network, although systems may be far from each other but reachable via the
Internet. They may be used to support IPv6 traffic on a network where the ISP
does not provide the service, or to extend and "connect" separate local
networks. Please see for
more general information about tunnels.
The specific settings for tunnels are defined below.
- **mode** (scalar)
> Defines the tunnel mode. Valid options are `sit`, `gre`, `ip6gre`,
> `ipip`, `ipip6`, `ip6ip6`, `vti`, `vti6`, `wireguard` and `vxlan`.
> Additionally, the `networkd` backend also supports `gretap` and
> `ip6gretap` modes.
> In addition, the `NetworkManager` backend supports `isatap` tunnels.
- **local** (scalar)
> Defines the address of the local endpoint of the tunnel. (For VXLAN) This
> should match one of the parent's IP addresses or make use of the networkd
> special values.
- **remote** (scalar)
> Defines the address of the remote endpoint of the tunnel or multicast group
> IP address for VXLAN.
- **ttl** (scalar) – since **0.103**
> Defines the Time To Live (TTL) of the tunnel.
> Takes a number in the range `1..255`.
- **key** (scalar or mapping)
> Define keys to use for the tunnel. The key can be a number or a dotted
> quad (an IPv4 address). For `wireguard` it can be a base64-encoded
> private key or (as of `networkd` v242+) an absolute path to a file,
> containing the private key (since 0.100).
> It is used for identification of IP transforms. This is only required
> for `vti` and `vti6` when using the networkd backend.
>
> This field may be used as a scalar (meaning that a single key is
> specified and to be used for input, output and private key), or as a
> mapping, where you can further specify `input`/`output`/`private`.
- **input** (scalar)
> The input key for the tunnel
- **output** (scalar)
> The output key for the tunnel
- **private** (scalar) – since **0.100**
> A base64-encoded private key required for WireGuard tunnels. When the
> `systemd-networkd` backend (v242+) is used, this can also be an
> absolute path to a file containing the private key.
- **keys** (scalar or mapping)
> Alternate name for the `key` field. See above.
Examples:
```yaml
network:
tunnels:
tun0:
mode: gre
local: ...
remote: ...
keys:
input: 1234
output: 5678
```
```yaml
network:
tunnels:
tun0:
mode: vti6
local: ...
remote: ...
key: 59568549
```
```yaml
network:
tunnels:
wg0:
mode: wireguard
addresses: [...]
peers:
- keys:
public: rlbInAj0qV69CysWPQY7KEBnKxpYCpaWqOs/dLevdWc=
shared: /path/to/shared.key
...
key: mNb7OIIXTdgW4khM7OFlzJ+UPs7lmcWHV7xjPgakMkQ=
```
```yaml
network:
tunnels:
wg0:
mode: wireguard
addresses: [...]
peers:
- keys:
public: rlbInAj0qV69CysWPQY7KEBnKxpYCpaWqOs/dLevdWc=
...
keys:
private: /path/to/priv.key
```
WireGuard specific keys:
- **mark** (scalar) – since **0.100**
> Firewall mark for outgoing WireGuard packets from this interface,
> optional.
- **port** (scalar) – since **0.100**
> UDP port to listen at or `auto`. Optional, defaults to `auto`.
- **peers** (sequence of mappings) – since **0.100**
> A list of peers, each having keys documented below.
Example:
```yaml
network:
tunnels:
wg0:
mode: wireguard
key: /path/to/private.key
mark: 42
port: 5182
peers:
- keys:
public: rlbInAj0qV69CysWPQY7KEBnKxpYCpaWqOs/dLevdWc=
allowed-ips: [0.0.0.0/0, "2001:fe:ad:de:ad:be:ef:1/24"]
keepalive: 23
endpoint: 1.2.3.4:5
- keys:
public: M9nt4YujIOmNrRmpIRTmYSfMdrpvE7u6WkG8FY8WjG4=
shared: /some/shared.key
allowed-ips: [10.10.10.20/24]
keepalive: 22
endpoint: 5.4.3.2:1
```
- **endpoint** (scalar) – since **0.100**
> Remote endpoint IPv4/IPv6 address or a hostname, followed by a colon
> and a port number.
- **allowed-ips** (sequence of scalars) – since **0.100**
> A list of IP (v4 or v6) addresses with CIDR masks from which this peer
> is allowed to send incoming traffic and to which outgoing traffic for
> this peer is directed. The catch-all 0.0.0.0/0 may be specified for
> matching all IPv4 addresses, and ::/0 may be specified for matching
> all IPv6 addresses.
- **keepalive** (scalar) – since **0.100**
> An interval in seconds, between 1 and 65535 inclusive, of how often to
> send an authenticated empty packet to the peer for the purpose of
> keeping a stateful firewall or NAT mapping valid persistently. Optional.
- **keys** (mapping) – since **0.100**
> Define keys to use for the WireGuard peers.
>
> This field can be used as a mapping, where you can further specify the
> `public` and `shared` keys.
- **public** (scalar) – since **0.100**
> A base64-encoded public key, required for WireGuard peers.
- **shared** (scalar) – since **0.100**
> A base64-encoded preshared key. Optional for WireGuard peers.
> When the `systemd-networkd` backend (v242+) is used, this can
> also be an absolute path to a file containing the preshared key.
VXLAN specific keys:
- **id** (scalar) – since **0.105**
> The VXLAN Network Identifier (VNI or VXLAN Segment ID).
> Takes a number in the range `1..16777215`.
- **link** (scalar) – since **0.105**
> netplan ID of the parent device definition to which this VXLAN gets
> connected.
- **type-of-service** (scalar) – since **0.105**
> The Type Of Service byte value for a vxlan interface.
- **mac-learning** (scalar) – since **0.105**
> Takes a boolean. When `true`, enables dynamic MAC learning to discover
> remote MAC addresses.
- **ageing**, **aging** (scalar) – since **0.105**
> The lifetime of Forwarding Database entry learned by the kernel, in
> seconds.
- **limit** (scalar) – since **0.105**
> Configures maximum number of FDB entries.
- **arp-proxy** (scalar) – since **0.105**
> Takes a boolean. When `true`, bridge-connected VXLAN tunnel endpoint
> answers ARP requests from the local bridge on behalf of remote Distributed
> Overlay Virtual Ethernet (DOVE) clients. Defaults to `false`.
- **notifications** (sequence of scalars) – since **0.105**
> Takes the flags `l2-miss` and `l3-miss` to enable netlink LLADDR and/or
> netlink IP address miss notifications.
- **short-circuit** (scalar) – since **0.105**
> Takes a boolean. When `true`, route short circuiting is turned on.
- **checksums** (sequence of scalars) – since **0.105**
> Takes the flags `udp`, `zero-udp6-tx`, `zero-udp6-rx`, `remote-tx` and
> `remote-rx` to enable transmitting UDP checksums in VXLAN/IPv4,
> send/receive zero checksums in VXLAN/IPv6 and enable sending/receiving
> checksum offloading in VXLAN.
- **extensions** (sequence of scalars) – since **0.105**
> Takes the flags `group-policy` and `generic-protocol` to enable the "Group
> Policy" and/or "Generic Protocol" VXLAN extensions.
- **port** (scalar) – since **0.105**
> Configures the default destination UDP port. If the destination port is
> not specified then Linux kernel default will be used. Set to `4789` to get
> the IANA assigned value.
- **port-range** (sequence of scalars) – since **0.105**
> Configures the source port range for the VXLAN. The kernel assigns the
> source UDP port based on the flow to help the receiver to do load
> balancing. When this option is not set, the normal range of local UDP
> ports is used. Uses the form `[LOWER, UPPER]`.
- **flow-label** (scalar) – since **0.105**
> Specifies the flow label to use in outgoing packets. The valid range
> is `0-1048575`.
- **do-not-fragment** (scalar) – since **0.105**
> Allows setting the IPv4 Do not Fragment (DF) bit in outgoing packets.
> Takes a boolean value. When unset, the kernel's default will be used.
## Properties for device type `vlans:`
**Status**: Optional.
**Purpose**: Use the `vlans` key to create VLAN interfaces.
**Structure**: The key consists of a mapping of VLAN interface names. The
interface used in the `link` option (`enp5s0` in the example below) must also be
defined in the Netplan configuration. The general configuration structure for
Vlans is shown below.
```yaml
network:
vlans:
vlan123:
id: 123
link: enp5s0
dhcp4: yes
```
The specific settings for VLANs are defined below.
- **id** (scalar)
> VLAN ID, a number between `0` and `4094`.
- **link** (scalar)
> netplan ID of the underlying device definition on which this VLAN gets
> created.
Example:
```yaml
network:
ethernets:
eno1: {...}
vlans:
en-intra:
id: 1
link: eno1
dhcp4: yes
en-vpn:
id: 2
link: eno1
addresses: [...]
```
## Properties for device type `vrfs:`
**Status**: Optional.
**Purpose**: Use the `vrfs` key to create Virtual Routing and Forwarding (VRF)
interfaces.
**Structure**: The key consists of a mapping of VRF interface names. The
interface used in the `link` option (`enp5s0` in the example below) must also be
defined in the Netplan configuration. The general configuration structure for
VRFs is shown below.
```yaml
network:
renderer: networkd
vrfs:
vrf1:
table: 1
interfaces:
- enp5s0
routes:
- to: default
via: 10.10.10.4
routing-policy:
- from: 10.10.10.42
```
- **table** (scalar) – since **0.105**
> The numeric routing table identifier. This setting is compulsory.
- **interfaces** (sequence of scalars) – since **0.105**
> All devices matching this ID list will be added to the VRF. This may
> be an empty list, in which case the VRF will be brought online with
> no member interfaces.
- **routes** (sequence of mappings) – since **0.105**
> Configure static routing for the device; see the `Routing` section.
> The `table` value is implicitly set to the VRF's `table`.
- **routing-policy** (sequence of mappings) – since **0.105**
> Configure policy routing for the device; see the ``Routing`` section.
> The `table` value is implicitly set to the VRF's `table`.
Example:
```yaml
network:
vrfs:
vrf20:
table: 20
interfaces: [ br0 ]
routes:
- to: default
via: 10.10.10.3
routing-policy:
- from: 10.10.10.42
[...]
bridges:
br0:
interfaces: []
```
## Properties for device type `nm-devices:`
**Status**: Optional. Its use is not recommended.
**Purpose**: Use the `nm-devices` key to configure device types that are not
supported by Netplan. This is NetworkManager specific configuration.
**Structure**: The key consists of a mapping of NetworkManager connections. The
`nm-devices` device type is for internal use only and should not be used in
normal configuration files. It enables a fallback mode for unsupported settings,
using the `passthrough` mapping. The general configuration structure for NM
connections is shown below.
```yaml
network:
version: 2
nm-devices:
NM-db5f0f67-1f4c-4d59-8ab8-3d278389cf87:
renderer: NetworkManager
networkmanager:
uuid: "db5f0f67-1f4c-4d59-8ab8-3d278389cf87"
name: "myvpnconnection"
passthrough:
connection.type: "vpn"
vpn.ca: "path to ca.crt"
vpn.cert: "path to client.crt"
vpn.cipher: "AES-256-GCM"
vpn.connection-type: "tls"
vpn.dev: "tun"
vpn.key: "path to client.key"
vpn.remote: "1.2.3.4:1194"
vpn.service-type: "org.freedesktop.NetworkManager.openvpn"
```
## Backend-specific configuration parameters
In addition to the other fields available to configure interfaces, some
backends may require to record some of their own parameters in netplan,
especially if the netplan definitions are generated automatically by the
consumer of that backend. Currently, this is only used with `NetworkManager`.
- **networkmanager** (mapping) – since **0.99**
> Keeps the NetworkManager-specific configuration parameters used by the
> daemon to recognize connections.
- **name** (scalar) – since **0.99**
> Set the display name for the connection.
- **uuid** (scalar) – since **0.99**
> Defines the UUID (unique identifier) for this connection, as
> generated by NetworkManager itself.
- **stable-id** (scalar) – since **0.99**
> Defines the stable ID (a different form of a connection name) used
> by NetworkManager in case the name of the connection might otherwise
> change, such as when sharing connections between users.
- **device** (scalar) – since **0.99**
> Defines the interface name for which this connection applies.
- **passthrough** (mapping) – since **0.102**
> Can be used as a fallback mechanism to missing keyfile settings.
netplan-0.106.1/doc/netplan.md 0000777 0000000 0000000 00000000000 14431205264 0020767 2netplan-yaml.md ustar 00root root 0000000 0000000 netplan-0.106.1/doc/netplan.svg 0000664 0000000 0000000 00000006104 14431205264 0016251 0 ustar 00root root 0000000 0000000
netplan-0.106.1/doc/reference.md 0000664 0000000 0000000 00000003375 14431205264 0016356 0 ustar 00root root 0000000 0000000 # Reference
## YAML configuration
Netplan's configuration files use the
[YAML (v1.1)]() format. All files in
`/{lib,etc,run}/netplan/*.yaml` are considered and are supposed to use
restrictive file permissions (`600` / `rw-------`), i.e. owner (root) read-write
only.
The top-level node in a netplan configuration file is a ``network:`` mapping
that contains ``version: 2`` (the YAML currently being used by curtin, MaaS,
etc. is version 1), and then device definitions grouped by their type, such as
``ethernets:``, ``modems:``, ``wifis:``, or ``bridges:``. These are the types
that our renderer can understand and are supported by our backends.
```{toctree}
---
maxdepth: 1
---
netplan-yaml
```
## API specification
`libnetplan` is a component of the Netplan. project that contains the logic for
data parsing, validation and generation. It is build as a dynamic `.so` library
that can be used from different binaries (like Netplan’s `generate`,
`netplan-dbus`, the `netplan apply/try/get/set/...` CLI or via the corresponding
Python bindings or external applications like the NetworkManager, using the
Netplan backend).
```{toctree}
API specification
```
## Netplan CLI
Netplan's manpages describe the usage of the different command line interface
tools available. Those are also installed on a system running Netplan and can be
accessed, using the `man` utility.
```{toctree}
---
maxdepth: 2
---
cli
```
## Netplan D-Bus
Netplan provides a daemon that can be run to provide the `io.netplan.Netplan`
D-Bus API, to control certain aspects of a system's Netplan configuration
programmatically. See also: [DBus config API](/dbus-config).
```{toctree}
---
maxdepth: 1
---
Netplan D-Bus
```
netplan-0.106.1/doc/requirements.txt 0000664 0000000 0000000 00000000152 14431205264 0017350 0 ustar 00root root 0000000 0000000 sphinx
furo
sphinx-design
sphinxcontrib-spelling
sphinx-autobuild
pyenchant
myst-parser
sphinx-copybutton
netplan-0.106.1/doc/spelling_wordlist.txt 0000664 0000000 0000000 00000001165 14431205264 0020376 0 ustar 00root root 0000000 0000000 abc
anycast
backend
Backend
backends
blackhole
bootup
cancelled
checksums
checksumming
config
ConnectX
curtin
dbus
DBus
dhcp
dmesg
engreen
enred
ethernet
failover
Fi
hostname
ifnames
initramfs
ip
ipip
iptables
ipv
IoT
IPv
keyfile
libnetplan
libvirt
libvirtd
loopback
lxd
Libera
MaaS
manpages
Mellanox
miimon
multicast
nameservers
nat
natively
netlink
netplan
networkd
NetworkManager
openvswitch
ovs
pre
prefixtlb
preshared
programmatically
ra
SSIDs
stateful
statelessly
subnet
subtree
systemd
tcp
timesyncd
tlb
tunnelled
tx
udev
unencrypted
unicast
veth
vlan
vrf
vsctl
vxlan
vSwitch
Wi
wifi
wifis
wpa
wpasupplicant
xresolve
yaml
netplan-0.106.1/doc/structure-id.md 0000664 0000000 0000000 00000010026 14431205264 0017041 0 ustar 00root root 0000000 0000000 ## Introduction
Distribution installers, cloud instantiation, image builds for particular
devices, or any other way to deploy an operating system put its desired
network configuration into YAML configuration file(s). During
early boot, the netplan "network renderer" runs which reads
`/{lib,etc,run}/netplan/*.yaml` and writes configuration to `/run` to hand
off control of devices to the specified networking daemon.
- Configured devices get handled by systemd-networkd by default,
unless explicitly marked as managed by a specific renderer (NetworkManager)
- Devices not covered by the network config do not get touched at all.
- Usable in initramfs (few dependencies and fast)
- No persistent generated config, only original YAML config
- Parser supports multiple config files to allow applications like libvirt or
lxd to package up expected network config (`virbr0`, `lxdbr0`), or to change
the global default policy to use NetworkManager for everything.
- Retains the flexibility to change backends/policy later or adjust to
removing NetworkManager, as generated configuration is ephemeral.
## General structure
netplan's configuration files use the
[YAML](http://yaml.org/spec/1.1/current.html) format. All
`/{lib,etc,run}/netplan/*.yaml` are considered. Lexicographically later files
(regardless of in which directory they are) amend (new mapping keys) or
override (same mapping keys) previous ones. A file in `/run/netplan`
completely shadows a file with same name in `/etc/netplan`, and a file in
either of those directories shadows a file with the same name in `/lib/netplan`.
The top-level node in a netplan configuration file is a `network:` mapping
that contains `version: 2` (the YAML currently being used by curtin, MaaS,
etc. is version 1), and then device definitions grouped by their type, such as
`ethernets:`, `modems:`, `wifis:`, or `bridges:`. These are the types that our
renderer can understand and are supported by our backends.
Each type block contains device definitions as a map where the keys (called
"configuration IDs") are defined as below.
## Device configuration IDs
The key names below the per-device-type definition maps (like `ethernets:`)
are called "ID"s. They must be unique throughout the entire set of
configuration files. Their primary purpose is to serve as anchor names for
composite devices, for example to enumerate the members of a bridge that is
currently being defined.
(Since 0.97) If an interface is defined with an ID in a configuration file; it
will be brought up by the applicable renderer. To not have netplan touch an
interface at all, it should be completely omitted from the netplan configuration
files.
There are two physically/structurally different classes of device definitions,
and the ID field has a different interpretation for each:
Physical devices
> (Examples: ethernet, modem, wifi) These can dynamically come and go between
> reboots and even during runtime (hot plugging). In the generic case, they
> can be selected by `match:` rules on desired properties, such as name/name
> pattern, MAC address, driver, or device paths. In general these will match
> any number of devices (unless they refer to properties which are unique
> such as the full path or MAC address), so without further knowledge about
> the hardware these will always be considered as a group.
>
> It is valid to specify no match rules at all, in which case the ID field is
> simply the interface name to be matched. This is mostly useful if you want
> to keep simple cases simple, and it's how network device configuration has
> been done for a long time.
>
> If there are ``match``: rules, then the ID field is a purely opaque name
> which is only being used for references from definitions of compound
> devices in the config.
Virtual devices
> (Examples: veth, bridge, bond, vrf) These are fully under the control of the
> config file(s) and the network stack. I. e. these devices are being created
> instead of matched. Thus `match:` and `set-name:` are not applicable for
> these, and the ID field is the name of the created virtual device.
netplan-0.106.1/doc/tutorial.md 0000664 0000000 0000000 00000000056 14431205264 0016254 0 ustar 00root root 0000000 0000000 # Tutorial
```{toctree}
netplan-tutorial
```
netplan-0.106.1/examples/ 0000775 0000000 0000000 00000000000 14431205264 0015137 5 ustar 00root root 0000000 0000000 netplan-0.106.1/examples/bonding.yaml 0000664 0000000 0000000 00000000365 14431205264 0017447 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
ethernets:
enp3s0: {}
enp4s0: {}
bonds:
bond0:
dhcp4: yes
interfaces:
- enp3s0
- enp4s0
parameters:
mode: active-backup
primary: enp3s0
netplan-0.106.1/examples/bonding_router.yaml 0000664 0000000 0000000 00000001715 14431205264 0021047 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
ethernets:
enp1s0:
dhcp4: no
enp2s0:
dhcp4: no
enp3s0:
dhcp4: no
optional: true
enp4s0:
dhcp4: no
optional: true
enp5s0:
dhcp4: no
optional: true
enp6s0:
dhcp4: no
optional: true
bonds:
bond-lan:
interfaces: [enp2s0, enp3s0]
addresses: [192.168.93.2/24]
parameters:
mode: 802.3ad
mii-monitor-interval: 1
bond-wan:
interfaces: [enp1s0, enp4s0]
addresses: [192.168.1.252/24]
nameservers:
search: [local]
addresses: [8.8.8.8, 8.8.4.4]
parameters:
mode: active-backup
mii-monitor-interval: 1
gratuitious-arp: 5
routes:
- to: default
via: 192.168.1.1
bond-conntrack:
interfaces: [enp5s0, enp6s0]
addresses: [192.168.254.2/24]
parameters:
mode: balance-rr
mii-monitor-interval: 1
netplan-0.106.1/examples/bridge.yaml 0000664 0000000 0000000 00000000234 14431205264 0017256 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
ethernets:
enp3s0:
dhcp4: no
bridges:
br0:
dhcp4: yes
interfaces:
- enp3s0
netplan-0.106.1/examples/bridge_vlan.yaml 0000664 0000000 0000000 00000000365 14431205264 0020303 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
ethernets:
enp0s25:
dhcp4: true
bridges:
br0:
addresses: [ 10.3.99.25/24 ]
interfaces: [ vlan15 ]
vlans:
vlan15:
accept-ra: no
id: 15
link: enp0s25
netplan-0.106.1/examples/dhcp.yaml 0000664 0000000 0000000 00000000126 14431205264 0016740 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
ethernets:
enp3s0:
dhcp4: true
netplan-0.106.1/examples/dhcp_wired8021x.yaml 0000664 0000000 0000000 00000000330 14431205264 0020632 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
ethernets:
enp3s0:
dhcp4: true
auth:
key-management: 802.1x
method: ttls
identity: fluffy@cisco.com
password: hash:83...11
netplan-0.106.1/examples/direct_connect_gateway.yaml 0000664 0000000 0000000 00000000274 14431205264 0022532 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
ethernets:
eth0:
addresses: [ "10.10.10.1/24" ]
routes:
- to: 0.0.0.0/0
via: 9.9.9.9
on-link: true
netplan-0.106.1/examples/direct_connect_gateway_ipv6.yaml 0000664 0000000 0000000 00000000331 14431205264 0023470 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
ethernets:
eth0:
addresses: [ "2001:cafe:face:beef::dead:dead/64" ]
routes:
- to: "::/0"
via: "2001:cafe:face::1"
on-link: true
netplan-0.106.1/examples/infiniband.yaml 0000664 0000000 0000000 00000000325 14431205264 0020124 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
ethernets:
ib0:
match:
macaddress: "11:22:33:44:55:66:77:88:99:00:11:22:33:44:55:66:77:88:99:00"
dhcp4: true
infiniband-mode: "connected"
netplan-0.106.1/examples/ipv6_tunnel.yaml 0000664 0000000 0000000 00000000575 14431205264 0020303 0 ustar 00root root 0000000 0000000 network:
version: 2
ethernets:
eth0:
addresses:
- 1.1.1.1/24
- "2001:cafe:face::1/64"
routes:
- to: default
via: 1.1.1.254
tunnels:
he-ipv6:
mode: sit
remote: 2.2.2.2
local: 1.1.1.1
addresses:
- "2001:dead:beef::2/64"
routes:
- to: default
via: "2001:dead:beef::1"
netplan-0.106.1/examples/loopback_interface.yaml 0000664 0000000 0000000 00000000176 14431205264 0021641 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
ethernets:
lo:
match:
name: lo
addresses: [ 7.7.7.7/32 ]
netplan-0.106.1/examples/meson.build 0000664 0000000 0000000 00000000422 14431205264 0017277 0 ustar 00root root 0000000 0000000 #https://mesonbuild.com/FAQ.html#but-i-really-want-to-use-wildcards
c = run_command(find, '-name', '*.yaml', check: true)
examples = c.stdout().strip().split('\n')
install_data(
examples,
install_dir: join_paths(get_option('datadir'), 'doc', 'netplan', 'examples'))
netplan-0.106.1/examples/modem.yaml 0000664 0000000 0000000 00000000550 14431205264 0017124 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: NetworkManager
modems:
cdc-wdm1:
mtu: 1600
apn: ISP.CINGULAR
username: ISP@CINGULARGPRS.COM
password: CINGULAR1
number: "*99#"
network-id: 24005
device-id: da812de91eec16620b06cd0ca5cbc7ea25245222
pin: 2345
sim-id: 89148000000060671234
sim-operator-id: 310260
netplan-0.106.1/examples/network_manager.yaml 0000664 0000000 0000000 00000000061 14431205264 0021203 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: NetworkManager
netplan-0.106.1/examples/offload.yaml 0000664 0000000 0000000 00000000463 14431205264 0017440 0 ustar 00root root 0000000 0000000 network:
version: 2
ethernets:
ens1:
receive-checksum-offload: false
transmit-checksum-offload: true
tcp-segmentation-offload: true
tcp6-segmentation-offload: true
generic-segmentation-offload: true
generic-receive-offload: true
large-receive-offload: true
netplan-0.106.1/examples/openvswitch.yaml 0000664 0000000 0000000 00000002127 14431205264 0020376 0 ustar 00root root 0000000 0000000 network:
version: 2
openvswitch:
protocols: [OpenFlow13, OpenFlow14, OpenFlow15]
ports:
- [patch0-1, patch1-0]
ssl:
ca-cert: /some/ca-cert.pem
certificate: /another/cert.pem
private-key: /private/key.pem
external-ids:
somekey: somevalue
other-config:
key: value
ethernets:
eth0:
addresses: [10.5.32.26/20]
openvswitch:
external-ids:
iface-id: mylocaliface
other-config:
disable-in-band: false
eth1: {}
bonds:
bond0:
interfaces: [patch1-0, eth1]
openvswitch:
lacp: passive
parameters:
mode: balance-tcp
bridges:
ovs0:
addresses: [10.5.48.11/20]
interfaces: [patch0-1, eth0, bond0]
openvswitch:
protocols: [OpenFlow10, OpenFlow11, OpenFlow12]
controller:
addresses: [unix:/var/run/openvswitch/ovs0.mgmt]
connection-mode: out-of-band
fail-mode: secure
mcast-snooping: true
external-ids:
iface-id: myhostname
other-config:
disable-in-band: true
netplan-0.106.1/examples/route_metric.yaml 0000664 0000000 0000000 00000000277 14431205264 0020532 0 ustar 00root root 0000000 0000000 network:
version: 2
ethernets:
enred:
dhcp4: yes
dhcp4-overrides:
route-metric: 100
engreen:
dhcp4: yes
dhcp4-overrides:
route-metric: 200
netplan-0.106.1/examples/source_routing.yaml 0000664 0000000 0000000 00000001061 14431205264 0021070 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
ethernets:
ens3:
addresses:
- 192.168.3.30/24
dhcp4: no
routes:
- to: 192.168.3.0/24
via: 192.168.3.1
table: 101
routing-policy:
- from: 192.168.3.0/24
table: 101
ens5:
addresses:
- 192.168.5.24/24
dhcp4: no
routes:
- to: default
via: 192.168.5.1
- to: 192.168.5.0/24
via: 192.168.5.1
table: 102
routing-policy:
- from: 192.168.5.0/24
table: 102
netplan-0.106.1/examples/sriov.yaml 0000664 0000000 0000000 00000000453 14431205264 0017167 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
ethernets:
eno1:
mtu: 9000
embedded-switch-mode: "switchdev"
enp1s16f1:
link: eno1
addresses : [ "10.15.98.25/24" ]
vf1:
match:
name: enp1s16f[2-3]
link: eno1
addresses : [ "10.15.99.25/24" ]
netplan-0.106.1/examples/sriov_vlan.yaml 0000664 0000000 0000000 00000000473 14431205264 0020211 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
ethernets:
eno1:
mtu: 9000
enp1s16f1:
link: eno1
addresses : [ "10.15.98.25/24" ]
vlans:
vlan1:
id: 15
link: enp1s16f1
addresses: [ "10.3.99.5/24" ]
vlan2_hw:
id: 10
link: enp1s16f1
renderer: sriov
netplan-0.106.1/examples/static.yaml 0000664 0000000 0000000 00000000420 14431205264 0017306 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
ethernets:
enp3s0:
addresses:
- 10.10.10.2/24
nameservers:
search: [mydomain, otherdomain]
addresses: [10.10.10.1, 1.1.1.1]
routes:
- to: default
via: 10.10.10.1
netplan-0.106.1/examples/static_multiaddress.yaml 0000664 0000000 0000000 00000000277 14431205264 0022100 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
ethernets:
enp3s0:
addresses:
- 10.100.1.38/24
- 10.100.1.39/24
routes:
- to: default
via: 10.100.1.1
netplan-0.106.1/examples/static_singlenic_multiip_multigateway.yaml 0000664 0000000 0000000 00000000531 14431205264 0025703 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
ethernets:
eno1:
addresses:
- 10.0.0.10/24
- 11.0.0.11/24
nameservers:
addresses:
- 8.8.8.8
- 8.8.4.4
routes:
- to: 0.0.0.0/0
via: 10.0.0.1
metric: 100
- to: 0.0.0.0/0
via: 11.0.0.1
metric: 200
netplan-0.106.1/examples/vlan.yaml 0000664 0000000 0000000 00000001152 14431205264 0016762 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
ethernets:
mainif:
match:
macaddress: "de:ad:be:ef:ca:fe"
set-name: mainif
addresses: [ "10.3.0.5/23" ]
nameservers:
addresses: [ "8.8.8.8", "8.8.4.4" ]
search: [ example.com ]
routes:
- to: default
via: 10.3.0.1
vlans:
vlan15:
id: 15
link: mainif
addresses: [ "10.3.99.5/24" ]
vlan10:
id: 10
link: mainif
addresses: [ "10.3.98.5/24" ]
nameservers:
addresses: [ "127.0.0.1" ]
search: [ domain1.example.com, domain2.example.com ]
netplan-0.106.1/examples/vrf.yaml 0000664 0000000 0000000 00000000460 14431205264 0016620 0 ustar 00root root 0000000 0000000 network:
renderer: networkd
vrfs:
vrf1005:
table: 1005
interfaces:
- br1
- br1005
routes:
- to: default
via: 10.10.10.4
routing-policy:
- from: 10.10.10.42
bridges:
br1:
interfaces: []
br1005:
interfaces: []
netplan-0.106.1/examples/vxlan.yaml 0000664 0000000 0000000 00000001255 14431205264 0017156 0 ustar 00root root 0000000 0000000 network:
renderer: networkd
ethernets:
lo:
addresses:
- 192.168.10.10/32
vrfs:
vrf1005:
table: 1005
interfaces:
- br1
- br1005
bridges:
br1:
interfaces:
- vxlan1
br1005:
interfaces:
- vxlan1005
tunnels:
vxlan1005:
mode: vxlan
id: 1005
link: lo
mtu: 8950
accept-ra: no
neigh-suppress: true
mac-learning: false
port: 4789
local: 192.168.10.10
vxlan1:
mode: vxlan
id: 1
link: lo
mtu: 8950
accept-ra: no
neigh-suppress: true
mac-learning: false
port: 4789
local: 192.168.10.10
netplan-0.106.1/examples/windows_dhcp_server.yaml 0000664 0000000 0000000 00000000133 14431205264 0022076 0 ustar 00root root 0000000 0000000 network:
version: 2
ethernets:
enp3s0:
dhcp4: yes
dhcp-identifier: mac
netplan-0.106.1/examples/wireguard.yaml 0000664 0000000 0000000 00000001667 14431205264 0020026 0 ustar 00root root 0000000 0000000 network:
version: 2
tunnels:
wg0: #server
mode: wireguard
addresses: [10.10.10.20/24]
key: 4GgaQCy68nzNsUE5aJ9fuLzHhB65tAlwbmA72MWnOm8=
mark: 42
port: 51820
peers:
- keys:
public: M9nt4YujIOmNrRmpIRTmYSfMdrpvE7u6WkG8FY8WjG4=
shared: 7voRZ/ojfXgfPOlswo3Lpma1RJq7qijIEEUEMShQFV8=
allowed-ips: [20.20.20.10/24]
routes:
- to: default
via: 10.10.10.21
metric: 100
wg1: #client
mode: wireguard
addresses: [20.20.20.10/24]
key: KPt9BzQjejRerEv8RMaFlpsD675gNexELOQRXt/AcH0=
peers:
- endpoint: 10.10.10.20:51820
allowed-ips: [0.0.0.0/0]
keys:
public: rlbInAj0qV69CysWPQY7KEBnKxpYCpaWqOs/dLevdWc=
shared: 7voRZ/ojfXgfPOlswo3Lpma1RJq7qijIEEUEMShQFV8=
keepalive: 21
routes:
- to: default
via: 20.20.20.11
metric: 200
netplan-0.106.1/examples/wireless.yaml 0000664 0000000 0000000 00000000562 14431205264 0017663 0 ustar 00root root 0000000 0000000 network:
version: 2
renderer: networkd
wifis:
wlp2s0b1:
regulatory-domain: "GB"
dhcp4: no
dhcp6: no
addresses: [192.168.0.21/24]
nameservers:
addresses: [192.168.0.1, 8.8.8.8]
access-points:
"network_ssid_name":
password: "**********"
routes:
- to: default
via: 192.168.0.1
netplan-0.106.1/examples/wpa_enterprise.yaml 0000664 0000000 0000000 00000001414 14431205264 0021052 0 ustar 00root root 0000000 0000000 network:
version: 2
wifis:
wl0:
access-points:
workplace:
auth:
key-management: eap
method: ttls
anonymous-identity: "@internal.example.com"
identity: "joe@internal.example.com"
password: "v3ryS3kr1t"
university:
auth:
key-management: eap
method: tls
anonymous-identity: "@cust.example.com"
identity: "cert-joe@cust.example.com"
ca-certificate: /etc/ssl/cust-cacrt.pem
client-certificate: /etc/ssl/cust-crt.pem
client-key: /etc/ssl/cust-key.pem
client-key-password: "d3cryptPr1v4t3K3y"
open-network:
auth:
key-management: none
dhcp4: yes
netplan-0.106.1/features_h_generator.sh 0000775 0000000 0000000 00000000531 14431205264 0020052 0 ustar 00root root 0000000 0000000 #!/bin/sh
BASE=$(dirname $0)
OUTPUT=$BASE/src/_features.h
INPUT=$BASE/src/[!_]*.[hc]
printf "#include \nstatic const char *feature_flags[] __attribute__((__unused__)) = {\n" > $OUTPUT
awk 'match ($0, /netplan-feature:.*/ ) { $0=substr($0, RSTART, RLENGTH); print "\""$2"\"," }' $INPUT >> $OUTPUT
echo "NULL, };" >> $OUTPUT
cat $OUTPUT
netplan-0.106.1/features_py_generator.sh 0000775 0000000 0000000 00000000474 14431205264 0020261 0 ustar 00root root 0000000 0000000 #!/bin/sh
BASE=$(dirname $0)
OUTPUT=$BASE/netplan/_features.py
INPUT=$BASE/src/[!_]*.[hc]
echo "# Generated file" > $OUTPUT
echo "NETPLAN_FEATURE_FLAGS = [" >> $OUTPUT
awk 'match ($0, /netplan-feature:.*/ ) { $0=substr($0, RSTART, RLENGTH); print " \""$2"\"," }' $INPUT >> $OUTPUT
echo "]" >> $OUTPUT
cat $OUTPUT
netplan-0.106.1/include/ 0000775 0000000 0000000 00000000000 14431205264 0014744 5 ustar 00root root 0000000 0000000 netplan-0.106.1/include/meson.build 0000664 0000000 0000000 00000000156 14431205264 0017110 0 ustar 00root root 0000000 0000000 install_headers('netplan.h', 'parse.h', 'parse-nm.h', 'util.h', 'types.h',
subdir: 'netplan')
netplan-0.106.1/include/netplan.h 0000664 0000000 0000000 00000010423 14431205264 0016556 0 ustar 00root root 0000000 0000000 /*
* Copyright (C) 2021 Canonical, Ltd.
* Author: Lukas Märdian
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; version 3.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see .
*/
#pragma once
#include
#include "types.h"
NETPLAN_PUBLIC NetplanState*
netplan_state_new();
NETPLAN_PUBLIC void
netplan_state_reset(NetplanState* np_state);
NETPLAN_PUBLIC void
netplan_state_clear(NetplanState** np_state);
NETPLAN_PUBLIC NetplanBackend
netplan_state_get_backend(const NetplanState* np_state);
NETPLAN_PUBLIC guint
netplan_state_get_netdefs_size(const NetplanState* np_state);
NETPLAN_PUBLIC NetplanNetDefinition*
netplan_state_get_netdef(const NetplanState* np_state, const char* id);
NETPLAN_PUBLIC gboolean
netplan_state_finish_nm_write(
const NetplanState* np_state,
const char* rootdir,
NetplanError** error);
NETPLAN_PUBLIC gboolean
netplan_state_finish_ovs_write(
const NetplanState* np_state,
const char* rootdir,
NetplanError** error);
NETPLAN_PUBLIC gboolean
netplan_state_finish_sriov_write(
const NetplanState* np_state,
const char* rootdir,
NetplanError** error);
/* Write the selected yaml file. All definitions that originate from this file,
* as well as those without any given origin, are written to it.
*/
NETPLAN_PUBLIC gboolean
netplan_state_write_yaml_file(
const NetplanState* np_state,
const char* filename,
const char* rootdir,
NetplanError** error);
/* Update all the YAML files that were used to create this state.
* The definitions without clear origin are written to @default_filename.
*/
NETPLAN_PUBLIC gboolean
netplan_state_update_yaml_hierarchy(
const NetplanState* np_state,
const char* default_filename,
const char* rootdir,
NetplanError** error);
/* Dump the whole yaml configuration into the given file, regardless of the origin
* of each definition.
*/
NETPLAN_PUBLIC gboolean
netplan_state_dump_yaml(
const NetplanState* np_state,
int output_fd,
NetplanError** error);
NETPLAN_PUBLIC gboolean
netplan_netdef_write_yaml(
const NetplanState* np_state,
const NetplanNetDefinition* netdef,
const char* rootdir,
NetplanError** error);
NETPLAN_PUBLIC ssize_t
netplan_netdef_get_filepath(const NetplanNetDefinition* netdef, char* out_buffer, size_t out_buffer_size);
NETPLAN_PUBLIC NetplanBackend
netplan_netdef_get_backend(const NetplanNetDefinition* netdef);
NETPLAN_PUBLIC NetplanDefType
netplan_netdef_get_type(const NetplanNetDefinition* netdef);
NETPLAN_PUBLIC ssize_t
netplan_netdef_get_id(const NetplanNetDefinition* netdef, char* out_buffer, size_t out_buffer_size);
NETPLAN_PUBLIC NetplanNetDefinition*
netplan_netdef_get_bridge_link(const NetplanNetDefinition* netdef);
NETPLAN_PUBLIC NetplanNetDefinition*
netplan_netdef_get_bond_link(const NetplanNetDefinition* netdef);
NETPLAN_PUBLIC NetplanNetDefinition*
netplan_netdef_get_peer_link(const NetplanNetDefinition* netdef);
NETPLAN_PUBLIC NetplanNetDefinition*
netplan_netdef_get_vlan_link(const NetplanNetDefinition* netdef);
NETPLAN_PUBLIC NetplanNetDefinition*
netplan_netdef_get_sriov_link(const NetplanNetDefinition* netdef);
NETPLAN_PUBLIC ssize_t
netplan_netdef_get_set_name(const NetplanNetDefinition* netdef, char* out_buffer, size_t out_buffer_size);
NETPLAN_PUBLIC gboolean
netplan_netdef_has_match(const NetplanNetDefinition* netdef);
NETPLAN_PUBLIC gboolean
netplan_netdef_match_interface(const NetplanNetDefinition* netdef, const char* name, const char* mac, const char* driver_name);
/********** Old API below this ***********/
NETPLAN_DEPRECATED NETPLAN_PUBLIC const char *
netplan_netdef_get_filename(const NetplanNetDefinition* netdef);
NETPLAN_PUBLIC void
write_netplan_conf(const NetplanNetDefinition* def, const char* rootdir);
netplan-0.106.1/include/parse-nm.h 0000664 0000000 0000000 00000001741 14431205264 0016642 0 ustar 00root root 0000000 0000000 /*
* Copyright (C) 2021 Canonical, Ltd.
* Author: Lukas Märdian
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; version 3.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see .
*/
#pragma once
#include "types.h"
#define NETPLAN_NM_EMPTY_GROUP "_"
NETPLAN_PUBLIC gboolean
netplan_parser_load_keyfile(NetplanParser* npp, const char* filename, NetplanError** error);
/********** Old API below this ***********/
NETPLAN_PUBLIC gboolean
netplan_parse_keyfile(const char* filename, GError** error);
netplan-0.106.1/include/parse.h 0000664 0000000 0000000 00000004347 14431205264 0016237 0 ustar 00root root 0000000 0000000 /*
* Copyright (C) 2016 Canonical, Ltd.
* Author: Martin Pitt
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; version 3.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see .
*/
#pragma once
#include
#include "types.h"
/****************************************************
* Functions
****************************************************/
NETPLAN_PUBLIC NetplanParser*
netplan_parser_new();
NETPLAN_PUBLIC void
netplan_parser_reset(NetplanParser *npp);
NETPLAN_PUBLIC void
netplan_parser_clear(NetplanParser **npp);
NETPLAN_PUBLIC gboolean
netplan_parser_load_yaml(NetplanParser* npp, const char* filename, NetplanError** error);
NETPLAN_PUBLIC gboolean
netplan_parser_load_yaml_from_fd(NetplanParser* npp, int input_fd, NetplanError** error);
NETPLAN_PUBLIC gboolean
netplan_parser_load_nullable_fields(NetplanParser* npp, int input_fd, NetplanError** error);
NETPLAN_PUBLIC gboolean
netplan_state_import_parser_results(NetplanState* np_state, NetplanParser* npp, NetplanError** error);
/* Load the overrides, i.e. all global values (like "renderer") or Netdef-IDs
* that are part of the given YAML patch (), and are supposed to be
* overridden inside the yaml hierarchy by the resulting origin_hint file.
* They are supposed to be parsed from the origin-hint file given in
* only. */
NETPLAN_PUBLIC gboolean
netplan_parser_load_nullable_overrides(
NetplanParser* npp, int input_fd, const char* constraint, GError** error);
/********** Old API below this ***********/
NETPLAN_PUBLIC gboolean
netplan_parse_yaml(const char* filename, GError** error);
NETPLAN_PUBLIC GHashTable*
netplan_finish_parse(GError** error);
NETPLAN_PUBLIC guint
netplan_clear_netdefs();
NETPLAN_PUBLIC NetplanBackend
netplan_get_global_backend();
netplan-0.106.1/include/types.h 0000664 0000000 0000000 00000004164 14431205264 0016266 0 ustar 00root root 0000000 0000000 /*
* Copyright (C) 2022 Canonical, Ltd.
* Author: Danilo Egea Gondolfo
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; version 3.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see .
*/
#pragma once
#define NETPLAN_PUBLIC __attribute__ ((visibility("default")))
#define NETPLAN_INTERNAL __attribute__ ((visibility("default")))
#define NETPLAN_ABI __attribute__ ((visibility("default")))
#define NETPLAN_DEPRECATED __attribute__ ((deprecated))
#define NETPLAN_BUFFER_TOO_SMALL -2
/****************************************************
* Parsed definitions
****************************************************/
#include
typedef enum {
NETPLAN_DEF_TYPE_NONE,
/* physical devices */
NETPLAN_DEF_TYPE_ETHERNET,
NETPLAN_DEF_TYPE_WIFI,
NETPLAN_DEF_TYPE_MODEM,
/* virtual devices */
NETPLAN_DEF_TYPE_VIRTUAL,
NETPLAN_DEF_TYPE_BRIDGE = NETPLAN_DEF_TYPE_VIRTUAL,
NETPLAN_DEF_TYPE_BOND,
NETPLAN_DEF_TYPE_VLAN,
NETPLAN_DEF_TYPE_TUNNEL,
NETPLAN_DEF_TYPE_PORT,
NETPLAN_DEF_TYPE_VRF,
/* Type fallback/passthrough */
NETPLAN_DEF_TYPE_NM,
NETPLAN_DEF_TYPE_MAX_
} NetplanDefType;
typedef struct netplan_parser NetplanParser;
/**
* Represent a configuration stanza
*/
typedef struct netplan_net_definition NetplanNetDefinition;
typedef struct netplan_state NetplanState;
typedef enum {
NETPLAN_BACKEND_NONE,
NETPLAN_BACKEND_NETWORKD,
NETPLAN_BACKEND_NM,
NETPLAN_BACKEND_OVS,
NETPLAN_BACKEND_MAX_,
} NetplanBackend;
typedef GError NetplanError;
typedef struct _NetplanStateIterator NetplanStateIterator;
struct _NetplanStateIterator {
void* placeholder;
};
netplan-0.106.1/include/util.h 0000664 0000000 0000000 00000004163 14431205264 0016076 0 ustar 00root root 0000000 0000000 /*
* Copyright (C) 2016 Canonical, Ltd.
* Author: Martin Pitt
*
* This program is free software; you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation; version 3.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see .
*/
#pragma once
#include
#include
#include "types.h"
NETPLAN_PUBLIC gboolean
netplan_delete_connection(const char* id, const char* rootdir);
NETPLAN_PUBLIC gboolean
netplan_generate(const char* rootdir);
NETPLAN_PUBLIC ssize_t
netplan_get_id_from_nm_filepath(const char* filename, const char* ssid, char* out_buffer, size_t out_buf_size);
NETPLAN_PUBLIC ssize_t
netplan_netdef_get_output_filename(const NetplanNetDefinition* netdef, const char* ssid, char* out_buffer, size_t out_buf_size);
NETPLAN_PUBLIC void
netplan_error_clear(NetplanError** error);
NETPLAN_PUBLIC ssize_t
netplan_error_message(NetplanError* error, char* buf, size_t buf_size);
/* u64 return value contains both GLib domain and error code. The two values are
* concatenated, so that the relevant data can easily be masked:
* (u32)domain | (u32)code */
NETPLAN_PUBLIC uint64_t
netplan_error_code(NetplanError* error);
NETPLAN_PUBLIC void
netplan_state_iterator_init(const NetplanState* np_state, NetplanStateIterator* iter);
NETPLAN_PUBLIC NetplanNetDefinition*
netplan_state_iterator_next(NetplanStateIterator* iter);
NETPLAN_PUBLIC gboolean
netplan_state_iterator_has_next(const NetplanStateIterator* iter);
/********** Old API below this ***********/
NETPLAN_DEPRECATED NETPLAN_PUBLIC gchar*
netplan_get_filename_by_id(const char* netdef_id, const char* rootdir);
NETPLAN_DEPRECATED NETPLAN_PUBLIC gchar*
netplan_get_id_from_nm_filename(const char* filename, const char* ssid);
netplan-0.106.1/meson.build 0000664 0000000 0000000 00000010770 14431205264 0015470 0 ustar 00root root 0000000 0000000 project('netplan', 'c',
version: '0.106.1',
license: 'GPL3',
default_options: [
'c_std=c99',
'warning_level=1',
'werror=true',
],
meson_version: '>= 0.61.0',
)
glib = dependency('glib-2.0')
gio = dependency('gio-2.0')
yaml = dependency('yaml-0.1')
uuid = dependency('uuid')
libsystemd = dependency('libsystemd')
meson_make_symlink = meson.current_source_dir() + '/tools/meson-make-symlink.sh'
systemd = dependency('systemd')
completions = dependency('bash-completion')
systemd_generator_dir = systemd.get_variable(pkgconfig: 'systemdsystemgeneratordir')
bash_completions_dir = completions.get_variable(pkgconfig: 'completionsdir', default_value: '/etc/bash_completion.d')
# Order: Fedora/Mageia/openSUSE || Debian/Ubuntu
pyflakes = find_program('pyflakes-3', 'pyflakes3', required: false)
pycodestyle = find_program('pycodestyle-3', 'pycodestyle', 'pep8', required: false)
pytest = find_program('pytest-3', 'pytest3') # also requires the pytest-cov plugin
pycoverage = find_program('coverage-3', 'python3-coverage')
pandoc = find_program('pandoc', required: false)
find = find_program('find')
add_project_arguments(
'-DSBINDIR="' + join_paths(get_option('prefix'), get_option('sbindir')) + '"',
'-D_GNU_SOURCE',
language: 'c')
inc = include_directories('include')
subdir('include')
subdir('src')
subdir('dbus')
subdir('netplan')
subdir('examples')
subdir('doc')
pkg_mod = import('pkgconfig')
pkg_mod.generate(
libraries: libnetplan,
subdirs: ['netplan'],
name: 'libnetplan',
filebase: 'netplan',
description: 'YAML network configuration abstraction runtime library')
install_data(
'netplan.completions',
rename: 'netplan',
install_dir: bash_completions_dir)
###########
# Testing #
###########
test_env = [
'PYTHONPATH=' + meson.current_source_dir(),
'LD_LIBRARY_PATH=' + join_paths(meson.current_build_dir(), 'src'),
'NETPLAN_GENERATE_PATH=' + join_paths(meson.current_build_dir(), 'src', 'generate'),
'NETPLAN_DBUS_CMD=' + join_paths(meson.current_build_dir(), 'dbus', 'netplan-dbus'),
'COVERAGE_PROCESS_START=' + join_paths(meson.current_source_dir(), '.coveragerc'),
'G_DEBUG=fatal_criticals',
]
if get_option('unit_testing')
subdir('tests/ctests')
endif
#FIXME: exclude doc/env/
test('linting',
pyflakes,
args: [meson.current_source_dir()])
test('codestyle',
pycodestyle,
args: ['--max-line-length=130', '--exclude=doc/env', meson.current_source_dir()])
test('documentation',
find_program('tests/validate_docs.sh'),
workdir: meson.current_source_dir())
test('legacy-tests',
find_program('tests/cli_legacy.py'),
timeout: 120,
env: test_env)
#TODO: split out dbus tests into own test() instance, to run in parallel
test('unit-tests',
pycoverage,
args: ['run', '-a', '-m', 'pytest', '-s', '-v', '--cov-append', meson.current_source_dir()],
timeout: 600,
env: test_env)
#TODO: the coverage section should probably be cleaned up a bit
if get_option('b_coverage')
message('Find coverage reports in /meson-logs/coveragereport[-py]/')
# Using gcovr instead of lcov/gcov.
# The 'ninja coverage' command will produce the html/txt reports for C implicitly
#lcov = find_program('lcov')
#gcov = find_program('gcov')
#genhtml = find_program('genhtml')
gcovr = find_program('gcovr')
ninja = find_program('ninja')
grep = find_program('grep')
test('coverage-c-output',
find_program('ninja'),
args: ['-C', meson.current_build_dir(), 'coverage'],
timeout: 60,
priority: -90, # run before 'coverage-c'
is_parallel: false)
test('coverage-c',
grep,
args: ['^TOTAL.*100%$', join_paths(meson.current_build_dir(), 'meson-logs', 'coverage.txt')],
priority: -99, # run last
is_parallel: false)
test('coverage-py-combine',
pycoverage,
args: ['combine', '-a', meson.current_build_dir()],
priority: -90, # run before 'coverage-py-output'
is_parallel: false)
test('coverage-py-output',
pycoverage,
args: ['html', '-d', join_paths(meson.current_build_dir(),
'meson-logs', 'coveragereport-py'), '--omit=/usr*'],
priority: -95, # run before 'coverage-py'
is_parallel: false)
test('coverage-py',
pycoverage,
args: ['report', '--omit=/usr*', '--show-missing', '--fail-under=100'],
priority: -99, # run last
is_parallel: false)
endif
netplan-0.106.1/meson_options.txt 0000664 0000000 0000000 00000000065 14431205264 0016757 0 ustar 00root root 0000000 0000000 option('unit_testing', type: 'boolean', value: true)
netplan-0.106.1/netplan.completions 0000664 0000000 0000000 00000005336 14431205264 0017247 0 ustar 00root root 0000000 0000000 # netplan(5) completion -*- shell-script -*-
_netplan_completions_filter() {
local words="$1"
local cur=${COMP_WORDS[COMP_CWORD]}
local result=()
if [[ "${cur:0:1}" == "-" ]]; then
echo "$words"
else
for word in $words; do
[[ "${word:0:1}" != "-" ]] && result+=("$word")
done
echo "${result[*]}"
fi
}
_netplan_completions() {
local cur=${COMP_WORDS[COMP_CWORD]}
local compwords=("${COMP_WORDS[@]:1:$COMP_CWORD-1}")
local compline="${compwords[*]}"
case "$compline" in
'ip leases'*)
while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_netplan_completions_filter "-h --help --debug --root-dir")" -- "$cur" )
;;
'generate'*)
while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_netplan_completions_filter "-h --help --debug --root-dir --mapping")" -- "$cur" )
;;
'rebind'*)
while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_netplan_completions_filter "-h --help --debug")" -- "$cur" )
;;
'status'*)
while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_netplan_completions_filter "-h --help --debug -a --all -f --format $(ls /sys/class/net 2> /dev/null)")" -- "$cur" )
;;
'apply'*)
while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_netplan_completions_filter "-h --help --debug --sriov-only --only-ovs-cleanup --state")" -- "$cur" )
;;
'help'*)
while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_netplan_completions_filter "-h --help")" -- "$cur" )
;;
'info'*)
while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_netplan_completions_filter "-h --help --debug --json --yaml")" -- "$cur" )
;;
'get'*)
while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_netplan_completions_filter "-h --help --debug --root-dir")" -- "$cur" )
;;
'set'*)
while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_netplan_completions_filter "-h --help --debug --origin-hint")" -- "$cur" )
;;
'try'*)
while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_netplan_completions_filter "-h --help --debug --config-file --timeout --state")" -- "$cur" )
;;
'ip'*)
while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_netplan_completions_filter "-h --help --debug help leases")" -- "$cur" )
;;
*)
while read -r; do COMPREPLY+=( "$REPLY" ); done < <( compgen -W "$(_netplan_completions_filter "-h --help --debug help apply generate get info ip set rebind status try")" -- "$cur" )
;;
esac
} &&
complete -F _netplan_completions netplan
# ex: filetype=sh
netplan-0.106.1/netplan/ 0000775 0000000 0000000 00000000000 14431205264 0014762 5 ustar 00root root 0000000 0000000 netplan-0.106.1/netplan/__init__.py 0000664 0000000 0000000 00000001374 14431205264 0017100 0 ustar 00root root 0000000 0000000 #!/usr/bin/python3
#
# Copyright (C) 2018 Canonical, Ltd.
# Author: Mathieu Trudel-Lapierre
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; version 3.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see .
from netplan.cli.core import Netplan
__all__ = [Netplan]
netplan-0.106.1/netplan/cli/ 0000775 0000000 0000000 00000000000 14431205264 0015531 5 ustar 00root root 0000000 0000000 netplan-0.106.1/netplan/cli/__init__.py 0000664 0000000 0000000 00000001301 14431205264 0017635 0 ustar 00root root 0000000 0000000 #!/usr/bin/python3
#
# Copyright (C) 2018 Canonical, Ltd.
# Author: Mathieu Trudel-Lapierre
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; version 3.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see .
netplan-0.106.1/netplan/cli/commands/ 0000775 0000000 0000000 00000000000 14431205264 0017332 5 ustar 00root root 0000000 0000000 netplan-0.106.1/netplan/cli/commands/__init__.py 0000664 0000000 0000000 00000002660 14431205264 0021447 0 ustar 00root root 0000000 0000000 #!/usr/bin/python3
#
# Copyright (C) 2018 Canonical, Ltd.
# Author: Mathieu Trudel-Lapierre
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; version 3.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see .
from netplan.cli.commands.apply import NetplanApply
from netplan.cli.commands.generate import NetplanGenerate
from netplan.cli.commands.ip import NetplanIp
from netplan.cli.commands.migrate import NetplanMigrate
from netplan.cli.commands.try_command import NetplanTry
from netplan.cli.commands.info import NetplanInfo
from netplan.cli.commands.set import NetplanSet
from netplan.cli.commands.get import NetplanGet
from netplan.cli.commands.sriov_rebind import NetplanSriovRebind
from netplan.cli.commands.status import NetplanStatus
__all__ = [
'NetplanApply',
'NetplanGenerate',
'NetplanIp',
'NetplanMigrate',
'NetplanTry',
'NetplanInfo',
'NetplanSet',
'NetplanGet',
'NetplanSriovRebind',
'NetplanStatus',
]
netplan-0.106.1/netplan/cli/commands/apply.py 0000664 0000000 0000000 00000047765 14431205264 0021054 0 ustar 00root root 0000000 0000000 #!/usr/bin/python3
#
# Copyright (C) 2018-2020 Canonical, Ltd.
# Author: Mathieu Trudel-Lapierre
# Author: Łukasz 'sil2100' Zemczak
# Author: Lukas 'slyon' Märdian
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; version 3.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see .
'''netplan apply command line'''
import logging
import os
import sys
import glob
import subprocess
import shutil
import netifaces
import time
import netplan.cli.utils as utils
from netplan.configmanager import ConfigManager, ConfigurationError
from netplan.cli.sriov import apply_sriov_config
from netplan.cli.ovs import OvsDbServerNotRunning, apply_ovs_cleanup
OVS_CLEANUP_SERVICE = 'netplan-ovs-cleanup.service'
IF_NAMESIZE = 16
class NetplanApply(utils.NetplanCommand):
def __init__(self):
super().__init__(command_id='apply',
description='Apply current netplan config to running system',
leaf=True)
self.sriov_only = False
self.only_ovs_cleanup = False
self.state = None # to be filled by the '--state' argument
def run(self): # pragma: nocover (covered in autopkgtest)
self.parser.add_argument('--sriov-only', action='store_true',
help='Only apply SR-IOV related configuration and exit')
self.parser.add_argument('--only-ovs-cleanup', action='store_true',
help='Only clean up old OpenVSwitch interfaces and exit')
self.parser.add_argument('--state',
help='Directory containing previous YAML configuration')
self.func = self.command_apply
self.parse_args()
self.run_command()
def command_apply(self, run_generate=True, sync=False, exit_on_error=True, state_dir=None): # pragma: nocover
config_manager = ConfigManager()
if state_dir:
self.state = state_dir
# For certain use-cases, we might want to only apply specific configuration.
# If we only need SR-IOV configuration, do that and exit early.
if self.sriov_only:
NetplanApply.process_sriov_config(config_manager, exit_on_error)
return
# If we only need OpenVSwitch cleanup, do that and exit early.
elif self.only_ovs_cleanup:
NetplanApply.process_ovs_cleanup(config_manager, False, False, exit_on_error)
return
# if we are inside a snap, then call dbus to run netplan apply instead
if "SNAP" in os.environ:
# TODO: maybe check if we are inside a classic snap and don't do
# this if we are in a classic snap?
busctl = shutil.which("busctl")
if busctl is None:
raise RuntimeError("missing busctl utility")
# XXX: DO NOT TOUCH or change this API call, it is used by snapd to communicate
# using core20 netplan binary/client/CLI on core18 base systems. Any change
# must be agreed upon with the snapd team, so we don't break support for
# base systems running older netplan versions.
# https://github.com/snapcore/snapd/pull/5915
res = subprocess.call([busctl, "call", "--quiet", "--system",
"io.netplan.Netplan", # the service
"/io/netplan/Netplan", # the object
"io.netplan.Netplan", # the interface
"Apply", # the method
])
if res != 0:
if exit_on_error:
sys.exit(res)
elif res == 130:
raise PermissionError(
"failed to communicate with dbus service")
else:
raise RuntimeError(
"failed to communicate with dbus service: error %s" % res)
else:
return
ovs_cleanup_service = '/run/systemd/system/netplan-ovs-cleanup.service'
old_files_networkd = bool(glob.glob('/run/systemd/network/*netplan-*'))
old_ovs_glob = glob.glob('/run/systemd/system/netplan-ovs-*')
# Ignore netplan-ovs-cleanup.service, as it can always be there
if ovs_cleanup_service in old_ovs_glob:
old_ovs_glob.remove(ovs_cleanup_service)
old_files_ovs = bool(old_ovs_glob)
old_nm_glob = glob.glob('/run/NetworkManager/system-connections/netplan-*')
nm_ifaces = utils.nm_interfaces(old_nm_glob, netifaces.interfaces())
old_files_nm = bool(old_nm_glob)
generator_call = []
generate_out = None
if 'NETPLAN_PROFILE' in os.environ:
generator_call.extend(['valgrind', '--leak-check=full'])
generate_out = subprocess.STDOUT
generator_call.append(utils.get_generator_path())
if run_generate and subprocess.call(generator_call, stderr=generate_out) != 0:
if exit_on_error:
sys.exit(os.EX_CONFIG)
else:
raise ConfigurationError("the configuration could not be generated")
devices = netifaces.interfaces()
# Re-start service when
# 1. We have configuration files for it
# 2. Previously we had config files for it but not anymore
# Ideally we should compare the content of the *netplan-* files before and
# after generation to minimize the number of re-starts, but the conditions
# above works too.
restart_networkd = bool(glob.glob('/run/systemd/network/*netplan-*'))
if not restart_networkd and old_files_networkd:
restart_networkd = True
restart_ovs_glob = glob.glob('/run/systemd/system/netplan-ovs-*')
# Ignore netplan-ovs-cleanup.service, as it can always be there
if ovs_cleanup_service in restart_ovs_glob:
restart_ovs_glob.remove(ovs_cleanup_service)
restart_ovs = bool(restart_ovs_glob)
if not restart_ovs and old_files_ovs:
# OVS is managed via systemd units
restart_networkd = True
restart_nm_glob = glob.glob('/run/NetworkManager/system-connections/netplan-*')
nm_ifaces.update(utils.nm_interfaces(restart_nm_glob, devices))
restart_nm = bool(restart_nm_glob)
if not restart_nm and old_files_nm:
restart_nm = True
# Running 'systemctl daemon-reload' will re-run the netplan systemd generator,
# so let's make sure we only run it iff we're willing to run 'netplan generate'
if run_generate:
utils.systemctl_daemon_reload()
# stop backends
if restart_networkd:
logging.debug('netplan generated networkd configuration changed, reloading networkd')
# Clean up any old netplan related OVS ports/bonds/bridges, if applicable
NetplanApply.process_ovs_cleanup(config_manager, old_files_ovs, restart_ovs, exit_on_error)
wpa_services = ['netplan-wpa-*.service']
# Historically (up to v0.98) we had netplan-wpa@*.service files, in case of an
# upgraded system, we need to make sure to stop those.
if utils.systemctl_is_active('netplan-wpa@*.service'):
wpa_services.insert(0, 'netplan-wpa@*.service')
utils.systemctl('stop', wpa_services, sync=sync)
else:
logging.debug('no netplan generated networkd configuration exists')
if restart_nm:
logging.debug('netplan generated NM configuration changed, restarting NM')
if utils.nm_running():
# restarting NM does not cause new config to be applied, need to shut down devices first
for device in devices:
if device not in nm_ifaces:
continue # do not touch this interface
# ignore failures here -- some/many devices might not be managed by NM
try:
utils.nmcli(['device', 'disconnect', device])
except subprocess.CalledProcessError:
pass
utils.systemctl_network_manager('stop', sync=sync)
else:
logging.debug('no netplan generated NM configuration exists')
# Refresh devices now; restarting a backend might have made something appear.
devices = netifaces.interfaces()
# evaluate config for extra steps we need to take (like renaming)
# for now, only applies to non-virtual (real) devices.
config_manager.parse()
changes = NetplanApply.process_link_changes(devices, config_manager)
# delete virtual interfaces that have been defined in a previous state
# but are not configured anymore in the current YAML
if self.state:
cm = ConfigManager(self.state)
cm.parse() # get previous configuration state
prev_links = cm.virtual_interfaces.keys()
curr_links = config_manager.virtual_interfaces.keys()
NetplanApply.clear_virtual_links(prev_links, curr_links, devices)
# if the interface is up, we can still apply some .link file changes
# but we cannot apply the interface rename via udev, as it won't touch
# the interface name, if it was already renamed once (e.g. during boot),
# because of the NamePolicy=keep default:
# https://www.freedesktop.org/software/systemd/man/systemd.net-naming-scheme.html
devices = netifaces.interfaces()
for device in devices:
logging.debug('netplan triggering .link rules for %s', device)
try:
subprocess.check_call(['udevadm', 'test-builtin',
'net_setup_link',
'/sys/class/net/' + device],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL)
subprocess.check_call(['udevadm', 'test',
'/sys/class/net/' + device],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL)
except subprocess.CalledProcessError:
logging.debug('Ignoring device without syspath: %s', device)
devices_after_udev = netifaces.interfaces()
# apply some more changes manually
for iface, settings in changes.items():
# rename non-critical network interfaces
new_name = settings.get('name')
if new_name:
if len(new_name) >= IF_NAMESIZE:
logging.warning('Interface name {} is too long. {} will not be renamed'.format(new_name, iface))
continue
if iface in devices and new_name in devices_after_udev:
logging.debug('Interface rename {} -> {} already happened.'.format(iface, new_name))
continue # re-name already happened via 'udevadm test'
# bring down the interface, using its current (matched) interface name
subprocess.check_call(['ip', 'link', 'set', 'dev', iface, 'down'],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL)
# rename the interface to the name given via 'set-name'
subprocess.check_call(['ip', 'link', 'set',
'dev', iface,
'name', settings.get('name')],
stdout=subprocess.DEVNULL,
stderr=subprocess.DEVNULL)
# Reloading of udev rules happens during 'netplan generate' already
# subprocess.check_call(['udevadm', 'control', '--reload-rules'])
subprocess.check_call(['udevadm', 'trigger', '--attr-match=subsystem=net'])
subprocess.check_call(['udevadm', 'settle'])
# apply any SR-IOV related changes, if applicable
NetplanApply.process_sriov_config(config_manager, exit_on_error)
# (re)set global regulatory domain
if os.path.exists('/run/systemd/system/netplan-regdom.service'):
utils.systemctl('start', ['netplan-regdom.service'])
# (re)start backends
if restart_networkd:
netplan_wpa = [os.path.basename(f) for f in glob.glob('/run/systemd/system/*.wants/netplan-wpa-*.service')]
# exclude the special 'netplan-ovs-cleanup.service' unit
netplan_ovs = [os.path.basename(f) for f in glob.glob('/run/systemd/system/*.wants/netplan-ovs-*.service')
if not f.endswith('/' + OVS_CLEANUP_SERVICE)]
# Run 'systemctl start' command synchronously, to avoid race conditions
# with 'oneshot' systemd service units, e.g. netplan-ovs-*.service.
try:
utils.networkctl_reload()
utils.networkctl_reconfigure(utils.networkd_interfaces())
except subprocess.CalledProcessError:
# (re-)start systemd-networkd if it is not running, yet
logging.warning('Falling back to a hard restart of systemd-networkd.service')
utils.systemctl('restart', ['systemd-networkd.service'], sync=True)
# 1st: execute OVS cleanup, to avoid races while applying OVS config
utils.systemctl('start', [OVS_CLEANUP_SERVICE], sync=True)
# 2nd: start all other services
utils.systemctl('start', netplan_wpa + netplan_ovs, sync=True)
if restart_nm:
# Flush all IP addresses of NM managed interfaces, to avoid NM creating
# new, non netplan-* connection profiles, using the existing IPs.
for iface in utils.nm_interfaces(restart_nm_glob, devices):
utils.ip_addr_flush(iface)
# clear NM state, especially the [device].managed=true config, as that might have been
# re-set via an udev rule setting "NM_UNMANAGED=1"
shutil.rmtree('/run/NetworkManager/devices', ignore_errors=True)
utils.systemctl_network_manager('start', sync=sync)
if sync:
# 'nmcli' could be /usr/bin/nmcli or
# /snap/bin/nmcli -> /snap/bin/network-manager.nmcli
cmd = ['nmcli', 'general', 'status']
# wait a bit for 'connected (site/local-only)' or
# 'connected' to appear in 'nmcli general' STATE
for _ in range(10):
out = subprocess.run(cmd, capture_output=True, text=True)
# Handle nmcli's "not running" return code (8) gracefully,
# giving some more time for NetworkManager startup
if out.returncode == 8:
time.sleep(1)
continue
if '\nconnected' in str(out.stdout):
break
time.sleep(0.5)
@staticmethod
def is_composite_member(composites, phy):
"""
Is this physical interface a member of a 'composite' virtual
interface? (bond, bridge)
"""
for composite in composites:
for _, settings in composite.items():
if not type(settings) is dict:
continue
members = settings.get('interfaces', [])
for iface in members:
if iface == phy:
return True
return False
@staticmethod
def clear_virtual_links(prev_links, curr_links, devices=[]):
"""
Calculate the delta of virtual links. And remove the links that were
dropped from the YAML config, if they were not dropped by the backend
already.
We can make use of the netplan netdef ids, as those equal the interface
name for virtual links.
"""
if not devices:
logging.warning('Cannot clear virtual links: no network interfaces provided.')
return []
dropped_interfaces = list(set(prev_links) - set(curr_links))
# some interfaces might have been cleaned up already, e.g. by the
# NetworkManager backend
interfaces_to_clear = list(set(dropped_interfaces).intersection(devices))
for link in interfaces_to_clear:
try:
cmd = ['ip', 'link', 'delete', 'dev', link]
subprocess.check_call(cmd)
except subprocess.CalledProcessError:
logging.warning('Could not delete interface {}'.format(link))
return dropped_interfaces
@staticmethod
def process_link_changes(interfaces, config_manager: ConfigManager): # pragma: nocover (covered in autopkgtest)
"""
Go through the pending changes and pick what needs special handling.
Only applies to non-critical interfaces which can be safely updated.
"""
changes = {}
composite_interfaces = [config_manager.bridges, config_manager.bonds]
# Find physical interfaces which need a rename
# But do not rename virtual interfaces
for netdef in config_manager.physical_interfaces.values():
newname = netdef.set_name
if not newname:
continue # Skip if no new name needs to be set
if not netdef.has_match:
continue # Skip if no match for current name is given
if NetplanApply.is_composite_member(composite_interfaces, netdef.id):
logging.debug('Skipping composite member {}'.format(netdef.id))
# do not rename members of virtual devices. MAC addresses
# may be the same for all interface members.
continue
# Find current name of the interface, according to match conditions and globs (name, mac, driver)
current_iface_name = utils.find_matching_iface(interfaces, netdef)
if not current_iface_name:
logging.warning('Cannot find unique matching interface for {}'.format(netdef.id))
continue
if current_iface_name == newname:
# Skip interface if it already has the correct name
logging.debug('Skipping correctly named interface: {}'.format(newname))
continue
if netdef.critical:
# Skip interfaces defined as critical, as we should not take them down in order to rename
logging.warning('Cannot rename {} ({} -> {}) at runtime (needs reboot), due to being critical'
.format(netdef.id, current_iface_name, newname))
continue
# record the interface rename change
changes[current_iface_name] = {'name': newname}
logging.debug('Link changes: {}'.format(changes))
return changes
@staticmethod
def process_sriov_config(config_manager, exit_on_error=True): # pragma: nocover (covered in autopkgtest)
try:
apply_sriov_config(config_manager)
except utils.config_errors as e:
logging.error(str(e))
if exit_on_error:
sys.exit(1)
@staticmethod
def process_ovs_cleanup(config_manager, ovs_old, ovs_current, exit_on_error=True): # pragma: nocover (autopkgtest)
try:
apply_ovs_cleanup(config_manager, ovs_old, ovs_current)
except (OSError, RuntimeError) as e:
logging.error(str(e))
if exit_on_error:
sys.exit(1)
except OvsDbServerNotRunning as e:
logging.warning('Cannot call Open vSwitch: {}.'.format(e))
netplan-0.106.1/netplan/cli/commands/generate.py 0000664 0000000 0000000 00000006722 14431205264 0021505 0 ustar 00root root 0000000 0000000 #!/usr/bin/python3
#
# Copyright (C) 2018 Canonical, Ltd.
# Author: Mathieu Trudel-Lapierre
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; version 3.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see .
'''netplan generate command line'''
import logging
import os
import sys
import subprocess
import shutil
import netplan.cli.utils as utils
class NetplanGenerate(utils.NetplanCommand):
def __init__(self):
super().__init__(command_id='generate',
description='Generate backend specific configuration files'
' from /etc/netplan/*.yaml',
leaf=True)
def run(self):
self.parser.add_argument('--root-dir',
help='Search for and generate configuration files in this root directory instead of /')
self.parser.add_argument('--mapping',
help='Display the netplan device ID/backend/interface name mapping and exit.')
self.func = self.command_generate
self.parse_args()
self.run_command()
def command_generate(self):
# if we are inside a snap, then call dbus to run netplan apply instead
if "SNAP" in os.environ:
# TODO: maybe check if we are inside a classic snap and don't do
# this if we are in a classic snap?
busctl = shutil.which("busctl")
if busctl is None:
raise RuntimeError("missing busctl utility") # pragma: nocover
# XXX: DO NOT TOUCH or change this API call, it is used by snapd to communicate
# using core20 netplan binary/client/CLI on core18 base systems. Any change
# must be agreed upon with the snapd team, so we don't break support for
# base systems running older netplan versions.
# https://github.com/snapcore/snapd/pull/10212
res = subprocess.call([busctl, "call", "--quiet", "--system",
"io.netplan.Netplan", # the service
"/io/netplan/Netplan", # the object
"io.netplan.Netplan", # the interface
"Generate", # the method
])
if res != 0:
if res == 130:
raise PermissionError(
"failed to communicate with dbus service")
else:
raise RuntimeError(
"failed to communicate with dbus service: error %s" % res)
else:
return
argv = [utils.get_generator_path()]
if self.root_dir:
argv += ['--root-dir', self.root_dir]
if self.mapping:
argv += ['--mapping', self.mapping]
logging.debug('command generate: running %s', argv)
# FIXME: os.execv(argv[0], argv) would be better but fails coverage
sys.exit(subprocess.call(argv))
netplan-0.106.1/netplan/cli/commands/get.py 0000664 0000000 0000000 00000005351 14431205264 0020467 0 ustar 00root root 0000000 0000000 #!/usr/bin/python3
#
# Copyright (C) 2020 Canonical, Ltd.
# Author: Lukas Märdian
#
# This program is free software; you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation; version 3.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see .
'''netplan get command line'''
import sys
import io
import tempfile
import re
import netplan.cli.utils as utils
import netplan.libnetplan as libnetplan
class NetplanGet(utils.NetplanCommand):
def __init__(self):
super().__init__(command_id='get',
description='Get a setting by specifying a nested key like "ethernets.eth0.addresses", or "all"',
leaf=True)
def run(self):
self.parser.add_argument('key', type=str, nargs='?', default='all', help='The nested key in dotted format')
self.parser.add_argument('--root-dir', default='/',
help='Read configuration files from this root directory instead of /')
self.func = self.command_get
self.parse_args()
self.run_command()
def dump_state(self, key, np_state, output_file):
if key == 'all':
np_state.dump_yaml(output_file=output_file)
return
if not key.startswith('network'):
key = '.'.join(('network', key))
# Replace the '.' with '\t' but not at '\.' via negative lookbehind expression
key = re.sub(r'(?