man: Add a quick start guide

Signed-off-by: Michael Tremer <michael.tremer@ipfire.org>

diff --git a/Makefile.am b/Makefile.am
index bd81906a484d7a57d9cf164ba22ab3a4cf159e3c..19f8e0c3cf44ebaf2e9ac3bfd3d1fbd18213db9d 100644 (file)
--- a/Makefile.am
+++ b/Makefile.am
@@ -335,6 +335,7 @@ MANPAGES = \
        man/network-dns-server.8 \
        man/network-port-batman-adv.8 \
        man/network-port-batman-adv-port.8 \
+       man/network-quick-start.8 \
        man/network-route.8 \
        man/network-settings.8 \
        man/network-zone.8 \

diff --git a/man/network-quick-start.xml b/man/network-quick-start.xml
new file mode 100644 (file)
index 0000000..ea79700
--- /dev/null
+++ b/man/network-quick-start.xml
@@ -0,0 +1,155 @@
+<?xml version="1.0"?>
+<!DOCTYPE refentry PUBLIC "-//OASIS/DTD DocBook XML V4.2//EN"
+       "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
+
+<refentry id="network">
+       <refentryinfo>
+               <title>network-quick-start</title>
+               <productname>network</productname>
+
+               <authorgroup>
+                       <author>
+                               <contrib>Developer</contrib>
+                               <firstname>Michael</firstname>
+                               <surname>Tremer</surname>
+                               <email>michael.tremer@ipfire.org</email>
+                       </author>
+               </authorgroup>
+       </refentryinfo>
+
+       <refmeta>
+               <refentrytitle>network-quick-start</refentrytitle>
+               <manvolnum>8</manvolnum>
+       </refmeta>
+
+       <refnamediv>
+               <refname>network-quick-start</refname>
+               <refpurpose>Network Configuration Control Program</refpurpose>
+       </refnamediv>
+
+       <refsect1>
+               <title>Quick Start Guide</title>
+
+               <para>
+                       The <command>network</command> is a very powerful command that allows
+                       you to configure the entire networking stack. Unfortunately that makes
+                       it quite complicated to use as well.
+                       This guide tries to be a good starting point to set up basic networking
+                       with the <command>network</command> command.
+               </para>
+       </refsect1>
+
+       <refsect1>
+               <title>Add an uplink zone</title>
+
+               <para>
+                       The first step is to create a new uplink zone with name
+                       <replaceable>upl0</replaceable>.
+                       This zone will be of the <replaceable>bridge</replaceable> type which is
+                       the default for all local networks.
+               </para>
+
+               <programlisting># network zone new <replaceable>upl0</replaceable> <replaceable>bridge</replaceable></programlisting>
+
+               <para>
+                       The zone will be created and brought up immediately.
+               </para>
+       </refsect1>
+
+       <refsect1>
+               <title>Attaching ports</title>
+
+               <para>
+                       To connect the zone to the physical world outside of our box we will need
+                       to attach ports to the zone.
+                       That is done with a single command.
+                       To execute this command, we will need to know which ports are available.
+                       One of the easiest way to find out about that is to use the auto-completion
+                       feature of the shell like this:
+               </para>
+
+               <programlisting># network zone <replaceable>upl0</replaceable> port attach [TAB] [TAB]</programlisting>
+
+               <para>
+                       That will list all not yet attached ports.
+                       The following command will actually attach the port
+                       (which is <replaceable>p0</replaceable> in this example).
+               </para>
+
+               <programlisting># network zone <replaceable>upl0</replaceable> port attach <replaceable>p0</replaceable></programlisting>
+
+               <para>
+                       You can as well get a list of all detected devices,
+                       zones and ports by running:
+               </para>
+
+               <programlisting># network device list</programlisting>
+
+               <para>
+                       To a zone of the <replaceable>bridge</replaceable> type you may attach more
+                       than just one port if you wish so.
+               </para>
+       </refsect1>
+
+       <refsect1>
+               <title>IP connectivity</title>
+
+               <para>
+                       After a zone has been created and ports have been attached, you are now
+                       able to add IP connectivity.
+                       The easiest way to do that is using DHCP which can be enabled by this
+                       simple command:
+               </para>
+
+               <programlisting># network zone <replaceable>upl0</replaceable> config new <replaceable>ipv6-dhcp</replaceable></programlisting>
+
+               <para>
+                       And for IPv4:
+               </para>
+
+               <programlisting># network zone <replaceable>upl0</replaceable> config new <replaceable>ipv4-dhcp</replaceable></programlisting>
+       </refsect1>
+
+       <refsect1>
+               <title>Debugging</title>
+
+               <para>
+                       You may see the current status of the network by running this command:
+               </para>
+
+               <programlisting># network status</programlisting>
+
+               <para>
+                       The entire network can be restarted by running:
+               </para>
+
+               <programlisting># network restart</programlisting>
+       </refsect1>
+
+       <refsect1>
+               <title>See Also</title>
+
+               <para>
+                       <citerefentry>
+                               <refentrytitle>network</refentrytitle>
+                               <manvolnum>8</manvolnum>
+                       </citerefentry>,
+                       <citerefentry>
+                               <refentrytitle>network-config</refentrytitle>
+                               <manvolnum>8</manvolnum>
+                       </citerefentry>,
+                       <citerefentry>
+                               <refentrytitle>network-device</refentrytitle>
+                               <manvolnum>8</manvolnum>
+                       </citerefentry>,
+                       <citerefentry>
+                               <refentrytitle>network-port</refentrytitle>
+                               <manvolnum>8</manvolnum>
+                       </citerefentry>,
+                       <citerefentry>
+                               <refentrytitle>network-zone</refentrytitle>
+                               <manvolnum>8</manvolnum>
+                       </citerefentry>
+               </para>
+       </refsect1>
+</refentry>

diff --git a/man/network.xml b/man/network.xml
index aee5057bd15fa7dbdf1a1422a983679ab0228b55..90ab27cf0a9b069a05a4a1ce2549105c58ba6183 100644 (file)
--- a/man/network.xml
+++ b/man/network.xml
@@ -330,6 +330,10 @@
                                <refentrytitle>network-port</refentrytitle>
                                <manvolnum>8</manvolnum>
                        </citerefentry>,
+                       <citerefentry>
+                               <refentrytitle>network-quick-start</refentrytitle>
+                               <manvolnum>8</manvolnum>
+                       </citerefentry>,
                        <citerefentry>
                                <refentrytitle>network-zone</refentrytitle>
                                <manvolnum>8</manvolnum>