man: Convert network-performance-tuning(8) to asciidoc

[people/ms/network.git] / man / network-zone.xml

<?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-zone">
	<refentryinfo>
		<title>network-zone</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-zone</refentrytitle>
		<manvolnum>8</manvolnum>
	</refmeta>

	<refnamediv>
		<refname>network-zone</refname>
		<refpurpose>Network Configuration Control Program</refpurpose>
	</refnamediv>

	<refsynopsisdiv>
		<cmdsynopsis>
			<command>network zone <arg choice="plain">[new|destroy]</arg> <replaceable>ZONE</replaceable> ...</command>
		</cmdsynopsis>

		<cmdsynopsis>
			<command>network zone <replaceable>ZONE</replaceable> <arg choice="plain">command</arg> ...</command>
		</cmdsynopsis>
	</refsynopsisdiv>

	<refsect1>
		<title>Description</title>

		<para>
			With help of the <command>zone</command> command, it is very easy to
			configure network zones.
		</para>
		<para>
			It is possible to create zones and remove them. Zones may also
			be brought up and down and reconfigured. Their status may be viewed
			as well.
		</para>
	</refsect1>

	<refsect1>
		<title>Commands</title>

		<para>
			The following commands are understood:
		</para>

		<variablelist>
			<varlistentry>
				<term>
					<command>new <replaceable>ZONE</replaceable> <replaceable>HOOK</replaceable> <arg choice="opt" rep="repeat">OPTIONS</arg></command>
				</term>

				<listitem>
					<para>
						A new zone may be created by the <command>create</command>
						command. There are at least two arguments required.
					</para>
					<para>
						<replaceable>ZONE</replaceable> must be valid name for a
						zone which does not already exist.
						<replaceable>HOOK</replaceable> is a valid zone hook which
						may require additional options.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>
					<command>destroy <replaceable>ZONE</replaceable></command>
				</term>

				<listitem>
					<para>
						A zone can be destroyed with this command.
					</para>
					<para>
						There are two possible ways to remove a zone. The case
						is when the zone is not up. Then, it will be removed
						immediately. When the zone is current up and used, it
						will tagged to be remove later, after it has been brought
						down.
					</para>
				</listitem>
			</varlistentry>
		</variablelist>

		<para>
			For all other commands, the name of the zone needs to be passed first:
		</para>

		<variablelist>
			<varlistentry>
				<term>
					<command><replaceable>ZONE</replaceable> edit <arg choice="opt" rep="repeat">OPTIONS</arg></command>
				</term>

				<listitem>
					<para>
						The settings of a zone may be edited after it has been created.
						The options that can be passed depend on the hook that is used
						for the zone.
						Run <command>network zone <replaceable>ZONE</replaceable> edit --help</command>
						to learn more about that.
					</para>
					<para>
						It usually is required to restart/reload the zone until
						the new settings are taken into account.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>
					<command><replaceable>ZONE</replaceable> [up|down]</command>
				</term>

				<listitem>
					<para>
						These commands will bring the zone up/down. This is done
						without control of systemd, therefore not intended to be
						done in a productive environment.
						However, these commands may be used for debugging.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>
					<command><replaceable>ZONE</replaceable> [enable|disable]</command>
				</term>

				<listitem>
					<para>
						These commands will enable or disable the zone. An enabled
						zone will automatically be started either during the boot process
						or a hotplug event of an associated port or other device.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>
					<command><replaceable>ZONE</replaceable> status</command>
				</term>

				<listitem>
					<para>
						This will show some detailed information about the state
						if the specified zone.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>
					<command><replaceable>ZONE</replaceable> color</command>
				</term>

				<listitem>
					<para>
						This command allows settings a color for a zone.
						See
						<citerefentry>
						<refentrytitle>network-color</refentrytitle>
						<manvolnum>8</manvolnum>
						</citerefentry>
						for more information.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>
					<command><replaceable>ZONE</replaceable>description</command>
				</term>

				<listitem>
					<para>
						This command make is possible to add a description to a zone.
						See
						<citerefentry>
						<refentrytitle>network-description</refentrytitle>
						<manvolnum>8</manvolnum>,
						</citerefentry>
						for more information.
					</para>
				</listitem>
			</varlistentry>
			<varlistentry>
				<term>
					<command><replaceable>ZONE</replaceable> identify</command>
				</term>

				<listitem>
					<para>
						This command will make all ports of the zone flash for
						a few seconds so that you can identify the correct network
						adapters in the system.
					</para>
				</listitem>
			</varlistentry>

			<varlistentry>
				<term>
					<command><replaceable>ZONE</replaceable> rename <replaceable>NAME</replaceable></command>
				</term>

				<listitem>
					<para>
						Renames the zone to <replaceable>NAME</replaceable>.
					</para>
					<para>
						The command will shut down the zone if it is up and
						start it again with the new name. If the zone is not
						up it won't be started.
					</para>
					<para>
						Zones that are marked to be destroyed cannot be renamed.
					</para>
				</listitem>
			</varlistentry>
		</variablelist>
	</refsect1>

	<refsect1>
		<title>See Also</title>

		<para>
			<citerefentry>
				<refentrytitle>network</refentrytitle>
				<manvolnum>8</manvolnum>
			</citerefentry>
		</para>
	</refsect1>
</refentry>