diff options
Diffstat (limited to 'metis/documentation/manpage-source')
| -rw-r--r-- | metis/documentation/manpage-source/Makefile.am | 80 | ||||
| -rw-r--r-- | metis/documentation/manpage-source/README | 21 | ||||
| -rw-r--r-- | metis/documentation/manpage-source/metis.cfg.sgml | 360 | ||||
| -rw-r--r-- | metis/documentation/manpage-source/metis_control.sgml | 164 | ||||
| -rw-r--r-- | metis/documentation/manpage-source/metis_daemon.sgml | 260 |
5 files changed, 885 insertions, 0 deletions
diff --git a/metis/documentation/manpage-source/Makefile.am b/metis/documentation/manpage-source/Makefile.am new file mode 100644 index 00000000..c130a91d --- /dev/null +++ b/metis/documentation/manpage-source/Makefile.am @@ -0,0 +1,80 @@ +# Copyright (c) 2017 Cisco and/or its affiliates. +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# +include ../../config.mk + +.PHONY: manpages + +SUBDIRS = + +OUTDIR= ../manpage + +MAN = $(OUTDIR)/metis_daemon.1 $(OUTDIR)/metis_control.1 $(OUTDIR)/metis.cfg.5 +TXT = $(OUTDIR)/metis_daemon.1.txt $(OUTDIR)/metis_control.1.txt $(OUTDIR)/metis.cfg.5.txt +HTML = $(OUTDIR)/metis_daemon.1.html $(OUTDIR)/metis_control.1.html $(OUTDIR)/metis.cfg.5.html +PDF = $(OUTDIR)/metis_daemon.1.pdf $(OUTDIR)/metis_control.1.pdf $(OUTDIR)/metis.cfg.5.pdf + +all: + @echo "usage: make manpages" + +manpages: $(TXT) $(MAN) $(HTML) $(PDF) + +$(OUTDIR): + mkdir -p $(OUTDIR) + +###### +$(OUTDIR)/metis_daemon.1: metis_daemon.sgml $(OUTDIR) + docbook-to-man $< > $@ + +$(OUTDIR)/metis_daemon.1.txt: $(OUTDIR)/metis_daemon.1 $(OUTDIR) + groff -man -Tutf8 $< > $@ + +$(OUTDIR)/metis_daemon.1.html: $(OUTDIR)/metis_daemon.1 $(OUTDIR) + groff -man -Thtml $< > $@ + +$(OUTDIR)/metis_daemon.1.pdf: $(OUTDIR)/metis_daemon.1 $(OUTDIR) + groff -man -Tps $< | ps2pdf - $@ + +###### +$(OUTDIR)/metis_control.1: metis_control.sgml $(OUTDIR) + docbook-to-man $< > $@ + +$(OUTDIR)/metis_control.1.txt: $(OUTDIR)/metis_control.1 $(OUTDIR) + groff -man -Tascii $< > $@ + +$(OUTDIR)/metis_control.1.html: $(OUTDIR)/metis_control.1 $(OUTDIR) + groff -man -Thtml $< > $@ + +$(OUTDIR)/metis_control.1.pdf: $(OUTDIR)/metis_control.1 $(OUTDIR) + groff -man -Tps $< | ps2pdf - $@ + +###### +$(OUTDIR)/metis.cfg.5: metis.cfg.sgml $(OUTDIR) + docbook-to-man $< > $@ + +$(OUTDIR)/metis.cfg.5.txt: $(OUTDIR)/metis.cfg.5 $(OUTDIR) + groff -man -Tascii $< > $@ + +$(OUTDIR)/metis.cfg.5.html: $(OUTDIR)/metis.cfg.5 $(OUTDIR) + groff -man -Thtml $< > $@ + +$(OUTDIR)/metis.cfg.5.pdf: $(OUTDIR)/metis.cfg.5 $(OUTDIR) + groff -man -Tps $< | ps2pdf - $@ + + +###### +#clobber: clean +# ${RM} -rf $(OUTDIR) +# +#CLEANFILES=$(TXT) $(MAN) $(HTML) + diff --git a/metis/documentation/manpage-source/README b/metis/documentation/manpage-source/README new file mode 100644 index 00000000..1aa7e48d --- /dev/null +++ b/metis/documentation/manpage-source/README @@ -0,0 +1,21 @@ +# Copyright (c) 2017 Cisco and/or its affiliates. +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at: +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. +# + +To process, it requires the following ubuntu packages installed: + + docbook docbook-to-man groff + +On other platforms, you can get software from http://www.docbook.org/, but +we have not tested docbook-to-man on Mac. + diff --git a/metis/documentation/manpage-source/metis.cfg.sgml b/metis/documentation/manpage-source/metis.cfg.sgml new file mode 100644 index 00000000..1cfee7d5 --- /dev/null +++ b/metis/documentation/manpage-source/metis.cfg.sgml @@ -0,0 +1,360 @@ +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> +<!-- --> +<!-- Copyright (c) 2017 Cisco and/or its affiliates. --> +<!-- Licensed under the Apache License, Version 2.0 (the "License"); --> +<!-- you may not use this file except in compliance with the License. --> +<!-- You may obtain a copy of the License at: --> +<!-- --> +<!-- http://www.apache.org/licenses/LICENSE-2.0 --> +<!-- --> +<!-- Unless required by applicable law or agreed to in writing, software --> +<!-- distributed under the License is distributed on an "AS IS" BASIS, --> +<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. --> +<!-- See the License for the specific language governing permissions and --> +<!-- limitations under the License. --> +<!-- --> +<!-- --> + +<refentry> +<refmeta> + <refentrytitle> + <filename>metis.cfg</filename> + </refentrytitle> + <manvolnum>5</manvolnum> +</refmeta> + +<refnamediv> + <refname> + <filename>metis.cfg</filename> + </refname> + <refpurpose> +<filename>metis.cfg</filename> is an example of a configuation file usable with +<citerefentry><refentrytitle>metis_daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>, +though there is nothing special about the actual filename. Each line of the configuration file is also usable with +<citerefentry><refentrytitle>metis_control</refentrytitle><manvolnum>1</manvolnum></citerefentry>. This +document specifies all available command lines used to configure and query Metis. + +All commands have a 'help', so typing 'help command' will display on-line help. + +In a configuration file, lines beginning with '#' are comments. + </refpurpose> +</refnamediv> + +<refsect1> + <title>ADD COMMANDS</title> + <variablelist> + <varlistentry> + <term>add connection ether <replaceable class="parameter">symbolic</replaceable> <replaceable class="parameter">dmac</replaceable> <replaceable class="parameter">interface</replaceable></term> + <listitem> + <para> + Adds an Ethernet connection on <replaceable class="parameter">interface</replaceable> to the given destination MAC address. + The <replaceable class="parameter">symbolic</replaceable> name is a symbolic name for the connection, which may be used in + later commands, such as <command>add route</command>. + There must be an Ethernet Listener on the specified interface (see <command>add listener</command>), and the connection + will use the same EtherType as the Listener. The <replaceable class="parameter">dmac</replaceable> destination MAC address + is in hexidecimal with optional "-" or ":" separators. + </para> + <para> + A connection is a target for a later route assignment or for use as an ingress identifier in the PIT. When using a broadcast + or group address for a connection, an Interest routed over that connection will be broadcast. Many receivers may respond. + When Metis receives a broadcast Interest it uses the unicast source MAC for the reverse route -- it will automatically create + a new connection for the source node and put that in the PIT entry, so a Content Object answering the broadcast Interest will + only be unicast to the previous hop. + </para> + <para> + add connection ether conn7 e8-06-88-cd-28-de em3 + </para> + <para> + add connection ether bcast0 FFFFFFFFFFFF eth0 + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>add connection (tcp|udp) <replaceable class="parameter">symbolic</replaceable> <replaceable class="parameter">remote_ip</replaceable> <replaceable class="parameter">remote_port</replaceable> <replaceable class="parameter">local_ip</replaceable> <replaceable class="parameter">local_port</replaceable></term> + <listitem> + <para> + Opens a connection to the specific <replaceable class="parameter">remote_ip</replaceable> (which may be a hostname, though you do not have control over IPv4 or IPv6 in this case) on <replaceable class="parameter">remote_port</replaceable>. The local endpoint is given by <replaceable class="parameter">local_ip</replaceable> <replaceable class="parameter">local_port</replaceable>. While the <replaceable class="parameter">local_ip</replaceable> <replaceable class="parameter">local_port</replaceable> are technically optional parameters, the system's choice of local address may not be what one expects or may be a different protocols (4 or 6). The default port is 9695. + </para> + <para> + A TCP connection will go through a TCP connection establishment and will not register as UP until the remote side accepts. If one side goes down, the TCP connection will not auto-restart if it becomes availble again. + </para> + <para> + A UDP connection will start in the UP state and will not go DOWN unless there is a serious network error. + </para> + <variablelist> + <varlistentry> + <term>Opens a connection to 1.1.1.1 on port 1200 from the local address 2.2.2.2 port 1300</term> + <listitem> + <para> + add connection tcp conn0 1.1.1.1 1200 2.2.2.2 1300 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>opens connection to IPv6 address on port 1300</term> + <listitem> + <para> + add connection udp barney2 fe80::aa20:66ff:fe00:314a 1300 + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>add listener (tcp|udp) <replaceable class="parameter">symbolic</replaceable> <replaceable class="parameter">ip_address</replaceable> <replaceable class="parameter">port</replaceable></term> + <term>add listener ether <replaceable class="parameter">symbolic</replaceable> <replaceable class="parameter">interfaceName</replaceable> <replaceable class="parameter">ethertype</replaceable></term> + <term>add listener local <replaceable class="parameter">symbolic</replaceable> <replaceable class="parameter">path</replaceable></term> + <listitem> + <para> + Adds a protocol listener to accept packets of a given protocol (TCP or UDP or Ethernet). + The <replaceable class="parameter">symbolic</replaceable> name represents the listener and will be used in future commands + such as access list restrictions. If using a configuration file on <command>metis_daemon</command>, you must include + a listener on localhost for local applications to use. + </para> + <para> + The <replaceable class="parameter">ip_address</replaceable> is the IPv4 or IPv6 local address to bind to. + The <replaceable class="parameter">port</replaceable> is the TCP or UDP port to bind to. + </para> + <para> + The <replaceable class="parameter">interfaceName</replaceable> is the interface to open a raw socket on (e.g. "eth0"). + The <replaceable class="parameter">ethertype</replaceable> is the EtherType to use, represented as a 0x hex number (e.g. 0x0801) + or an integer (e.g. 2049). + </para> + <para> + The <replaceable class="parameter">path</replaceable> parameter specifies the file path to a unix domain socket. Metis + will create this file and remove it when it exits. + </para> + <variablelist> + <varlistentry> + <term>Listens to 192.168.1.7 on tcp port 9695 with a symbolic name 'homenet'</term> + <listitem> + <para> + add listener tcp homenet 192.168.1.7 9695 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Listens to IPv6 localhost on udp port 9695</term> + <listitem> + <para> + add listener udp localhost6 ::1 9695 + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Listens to interface 'en0' on ethertype 0x0801</term> + <listitem> + <para> + add listener ether nic0 en0 0x0801 + </para> + </listitem> + </varlistentry> + </variablelist> + </listitem> + </varlistentry> + + <varlistentry> + <term>add route <replaceable class="parameter">symbolic</replaceable> <replaceable class="parameter">prefix</replaceable> <replaceable class="parameter">prefix</replaceable></term> + <listitem> + <para> + Adds a static route to a given <replaceable class="parameter">prefix</replaceable> to the FIB for longest match. + </para> + <para> + Currently, the <replaceable class="parameter">symbolic</replaceable> and <replaceable class="parameter">cost</replaceable> are not used. + </para> + </listitem> + </varlistentry> + + </variablelist> +</refsect1> + +<refsect1> + <title>LIST COMMANDS</title> + <variablelist> + <varlistentry> + <term>list connections</term> + <listitem> + <para> + Enumerates the current connections to Metis. These include all TCP, UDP, Unix Domain, and Ethernet peers. + Each connection has an connection ID (connid) and a state (UP or DOWN) followed by the local (to metis) and remote + addresses. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>list interfaces</term> + <listitem> + <para> + Enumerates the system interfaces available to Metis. Each interface has an Interface ID, a 'name' (e.g. 'eth0'), + an MTU as reported by the system, and one or more addresses. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>list routes</term> + <listitem> + <para> + Enumerates the routes installed in the FIB. + The <replaceable class="option">iface</replaceable> is the out-bound connection. + The <replaceable class="option">protocol</replaceable> is the the routing protocol that injected the route. + 'STATIC' means it was manually entered via <command>metis_control</command>. + <replaceable class="option">route</replaceable> is the route type. 'LONGEST' means longest matching prefix + and 'EXACT' means exact match. Only 'LONGEST' is supported. + <replaceable class="option">cost</replaceable> is the cost of the route. It is not used. + <replaceable class="option">next</replaceable> is the nexthop on a multiple access interface. it is not used + because the current implementation uses one connection (iface) per neighbor. + <replaceable class="option">prefix</replaceable> is the CCNx name prefix for the route. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>Examples</term> + <listitem> + <programlisting linenumbering="numbered"> +> list connections +23 UP inet4://127.0.0.1:9695 inet4://127.0.0.1:64260 TCP + +> list interfaces +int name lm MTU + 24 lo0 lm 16384 inet6://[::1%0]:0 +inet4://127.0.0.1:0 +inet6://[fe80::1%1]:0 + 25 en0 m 1500 link://3c-15-c2-e7-c5-ca +inet6://[fe80::3e15:c2ff:fee7:c5ca%4]:0 +inet4://13.1.110.60:0 +inet6://[2620::2e80:a015:3e15:c2ff:fee7:c5ca%0]:0 +inet6://[2620::2e80:a015:a4b2:7e10:61d1:8d97%0]:0 + 26 en1 m 1500 link://72-00-04-43-4e-50 +inet4://192.168.1.1:0 + 27 en2 m 1500 link://72-00-04-43-4e-51 + 28 bridge0 m 1500 link://3e-15-c2-7e-96-00 + 29 p2p0 m 2304 link://0e-15-c2-e7-c5-ca + +> list routes + iface protocol route cost next prefix + 23 STATIC LONGEST 1 ---.---.---.---/.... lci:/foo/bar +Done + </programlisting> + </listitem> + </varlistentry> + </variablelist> +</refsect1> + +<refsect1> + <title>REMOVE COMMANDS</title> + <variablelist> + <varlistentry> + <term>remove connection</term> + <listitem> + <para> + Not implemented. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>remove route</term> + <listitem> + <para> + Not implemented. + </para> + </listitem> + </varlistentry> + </variablelist> +</refsect1> + +<refsect1> + <title>MISC COMMANDS</title> + <variablelist> + <varlistentry> + <term>quit</term> + <listitem> + <para> + In interactive mode of <command>metis_control</command>, it cause the program to exit. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>set debug</term> + <listitem> + <para> + Turns on the debugging flag in <command>metis_control</command> to display information about its connection to Metis. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term>unset debug</term> + <listitem> + <para> + Turns off the debugging flag in <command>metis_control</command> to display information about its connection to Metis. + </para> + </listitem> + </varlistentry> + </variablelist> +</refsect1> + +<refsect1> + <title>USAGE</title> + <example><title>Example Linux metis.cfg configuration file</title> + <programlisting> +#local listeners for applications +add listener tcp local0 127.0.0.1 9695 +add listener udp local1 127.0.0.1 9695 +add listener local unix0 /tmp/metis.sock + +# add ethernet listener and connection +add listener ether nic0 eth0 0x0801 +add connection ether conn0 ff:ff:ff:ff:ff:ff eth0 +add route conn0 lci:/ 1 + +# add UDP tunnel to remote system +add connection udp conn1 ccnx.example.com 9695 +add route conn1 lci:/example.com 1 + </programlisting> + </example> + <example><title>Example one-shot metis_control commands</title> + <screen> + <command>metis_control</command> list routes + <command>metis_control</command> add listener local unix0 /tmp/metis.sock + </screen> + </example> +</refsect1> + +<refsect1> + <title>SEE ALSO</title> + <para> + <citerefentry><refentrytitle>metis_control</refentrytitle><manvolnum>1</manvolnum></citerefentry> + <citerefentry><refentrytitle>metis_daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry> + </para> +</refsect1> + +<refsect1> + <title>CAVEATS</title> + <para> + </para> +</refsect1> +<refsect1> + <title>BUGS</title> + <itemizedlist mark='opencircle'> + <listitem><para> + The output of 'list interfaces' is difficult to read because multiple addresses + do not align. + </para></listitem> + </itemizedlist> + +</refsect1> +<refsect1> + <title>AUTHOR</title> + <para> + <author> + <firstname>Marc</firstname> + <surname>Mosko</surname> + <contrib>Palo Alto Research Center</contrib> + </author> + </para> +</refsect1> +</refentry> + + diff --git a/metis/documentation/manpage-source/metis_control.sgml b/metis/documentation/manpage-source/metis_control.sgml new file mode 100644 index 00000000..61d8bfb8 --- /dev/null +++ b/metis/documentation/manpage-source/metis_control.sgml @@ -0,0 +1,164 @@ +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> +<!-- --> +<!-- Copyright (c) 2017 Cisco and/or its affiliates. --> +<!-- Licensed under the Apache License, Version 2.0 (the "License"); --> +<!-- you may not use this file except in compliance with the License. --> +<!-- You may obtain a copy of the License at: --> +<!-- --> +<!-- http://www.apache.org/licenses/LICENSE-2.0 --> +<!-- --> +<!-- Unless required by applicable law or agreed to in writing, software --> +<!-- distributed under the License is distributed on an "AS IS" BASIS, --> +<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. --> +<!-- See the License for the specific language governing permissions and --> +<!-- limitations under the License. --> +<!-- --> +<!-- --> +<refentry> +<refmeta> + <refentrytitle> + <application>metis_control</application> + </refentrytitle> + <manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> + <refname> + <application>metis_control</application> + </refname> + <refpurpose> +Metis is the CCNx 1.0 forwarder, which runs on each end system and as a software forwarder +on intermediate systems. <command>metis_control</command> is the program to configure the forwarder, +<command>metis_daemon</command>. + </refpurpose> +</refnamediv> + +<refsynopsisdiv> + <cmdsynopsis> + <command>metis_control</command> +<arg choice="opt"><option>--keystore</option> <replaceable class="parameter">keystore</replaceable></arg> +<arg choice="opt"><option>--password</option> <replaceable class="parameter">password</replaceable></arg> +<arg choice="opt">commandline</arg> + </cmdsynopsis> +</refsynopsisdiv> + +<refsect1> + <title>DESCRIPTION</title> + <para> + <command>metis_control</command> + is the program used to configure a running forwarder <command>metis_daemon</command>. It will connect to + the forwarder over a local listener (e.g. TCP to localhost or a unix domain socket). If a + <replaceable class="option">commandline</replaceable> option is specified, <command>metis_control</command> + will send that one command to Metis and then exit. If no <replaceable class="option">commandline</replaceable> + is specified, <command>metis_command</command> will enter interacitve mode where the user can issue + multiple commands. + </para> + <para> + <command>metis_control</command> requires a signing keystore for communicating over the network. The + <replaceable class="parameter">keystore</replaceable> file is a standard PKCS12 keystore, and may be + created using + <citerefentry><refentrytitle>parc_publickey</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + If no <replaceable class="parameter">keystore</replaceable> is specified, <command>metis_control</command> + will look in the standard path ~/.ccnx/.ccnx_keystore.p12. + The keystore password is specified in <replaceable class="parameter">password</replaceable>. If not specified, + no password is used. If the keystore does not open, the user will be prompted for a password. + </para> + <para> + See <citerefentry><refentrytitle>metis.cfg</refentrytitle><manvolnum>5</manvolnum></citerefentry> for + a specification of the available <replaceable class="option">commandline</replaceable>. + </para> + <para> + The environment variable METIS_PORT may be used to specify what TCP port to use to connect to the local Metis. + The environment variable METIS_LOCALPATH may be used to specific the UNIX domain socket to connect to the local Metis + and takes priority over METIS_PORT. + </para> +</refsect1> + +<refsect1> + <title>OPTIONS</title> + <variablelist> + + <varlistentry> + <term>--keystore <replaceable class="parameter">keystore</replaceable></term> + <listitem> + <para> + <command>metis_control</command> requires a signing keystore for communicating over the network. The + <replaceable class="parameter">keystore</replaceable> file is a standard PKCS12 keystore, and may be + created using + <citerefentry><refentrytitle>parc_publickey</refentrytitle><manvolnum>1</manvolnum></citerefentry>. + If no <replaceable class="parameter">keystore</replaceable> is specified, <command>metis_control</command> + will look in the standard path ~/.ccnx/.ccnx_keystore.p12. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>--password <replaceable class="parameter">password</replaceable></term> + <listitem> + <para> + The keystore password is specified in <replaceable class="parameter">password</replaceable>. If not specified, + no password is used. If the keystore does not open, the user will be prompted for a password. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>commandline</term> + <listitem> + <para> + The remainder of the arguments are the commandline to send to Metis. See USAGE. + </para> + </listitem> + </varlistentry> + + </variablelist> +</refsect1> +<refsect1> + <title>USAGE</title> + <para> + <command>metis_control</command> --keystore keystore.p12 + </para> + <para> + <command>metis_control</command> --keystore keystore.p12 list interfaces + </para> +</refsect1> + +<refsect1> + <title>SEE ALSO</title> + <para> + See <citerefentry><refentrytitle>parc_publickey</refentrytitle><manvolnum>1</manvolnum></citerefentry> for a utility + to create a PKCS keystore. + </para> + <para> + For a list of all configuration lines that may be used with + <command>metis_control</command> and by <replaceable class="option">--config</replaceable> configuration file, + see <citerefentry><refentrytitle>metis.cfg</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> + <para> + The default keystore is ~/.ccnx/.ccnx_keystore.p12. + </para> +</refsect1> + +<refsect1> + <title>CAVEATS</title> + <para> + </para> +</refsect1> +<refsect1> + <title>BUGS</title> + <para> + </para> +</refsect1> +<refsect1> + <title>AUTHOR</title> + <para> + <author> + <firstname>Marc</firstname> + <surname>Mosko</surname> + <contrib>Palo Alto Research Center</contrib> + </author> + </para> +</refsect1> +</refentry> + + diff --git a/metis/documentation/manpage-source/metis_daemon.sgml b/metis/documentation/manpage-source/metis_daemon.sgml new file mode 100644 index 00000000..ccc0cf9c --- /dev/null +++ b/metis/documentation/manpage-source/metis_daemon.sgml @@ -0,0 +1,260 @@ +<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN"> +<!-- --> +<!-- Copyright (c) 2017 Cisco and/or its affiliates. --> +<!-- Licensed under the Apache License, Version 2.0 (the "License"); --> +<!-- you may not use this file except in compliance with the License. --> +<!-- You may obtain a copy of the License at: --> +<!-- --> +<!-- http://www.apache.org/licenses/LICENSE-2.0 --> +<!-- --> +<!-- Unless required by applicable law or agreed to in writing, software --> +<!-- distributed under the License is distributed on an "AS IS" BASIS, --> +<!-- WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. --> +<!-- See the License for the specific language governing permissions and --> +<!-- limitations under the License. --> +<!-- --> +<!-- --> +<refentry> +<refmeta> + <refentrytitle> + <application>metis_daemon</application> + </refentrytitle> + <manvolnum>1</manvolnum> +</refmeta> + +<refnamediv> + <refname> + <application>metis_daemon</application> + </refname> + <refpurpose> +Metis is the CCNx 1.0 forwarder, which runs on each end system and as a software forwarder +on intermediate systems. + </refpurpose> +</refnamediv> + +<refsynopsisdiv> + <cmdsynopsis> + <command>metis_daemon</command> +<arg choice="opt"><option>--port</option> <replaceable class="parameter">port</replaceable></arg> +<arg choice="opt"><option>--daemon</option></arg> +<arg choice="opt"><option>--capacity</option> <replaceable class="parameter">contentStoreSize</replaceable></arg> +<arg choice="opt" rep="repeat"><option>--log</option> <replaceable class="parameter">facility=level</replaceable></arg> +<arg choice="opt"><option>--log-file</option> <replaceable class="parameter">logfile</replaceable></arg> +<arg choice="opt"><option>--config</option> <replaceable class="parameter">configfile</replaceable></arg> + </cmdsynopsis> +</refsynopsisdiv> + +<refsect1> + <title>DESCRIPTION</title> + <para> + <command>metis_daemon</command> +is the CCNx 1.0 forwarder, which runs on each end system and as a software forwarder +on intermediate systems. metis_daemon is the program to launch Metis, either as a console program +or a background daemon (detatched from console). Once running, use the program <command>metis_control</command> to +configure Metis. + </para> + <para> +Metis is structured as a set of Listeners, each of which handles a specific method of listening for packets. +For example, a TCP listener will accept connections on a specific TCP port on a specific local IP address. +An Ethernet listener will accept frames of a specific EtherType on a specific Interface. + </para> + <para> +When Metis accepts a connection, it will create a Connection entry in the ConnectionTable to represent that peer. +For Ethernet, a Connection is the tuple {dmac, smac, ethertype}. For TCP and UDP, it is the tuple {source IP, source port, +destination IP, destination port}. The connid (connection ID) becomes the reverse route index in the Pending Interest Table. + </para> +</refsect1> + +<refsect1> + <title>OPTIONS</title> + <variablelist> + + <varlistentry> + <term>--config <replaceable class="parameter">configfile</replaceable></term> + <listitem> + <para> + Reads configuration parameters from + <replaceable class="parameter">configfile</replaceable>. + The + <replaceable class="option">--port</replaceable> option has no effect in this mode + and Metis will not listen to any ports. This means that + <command>metis_control</command> will not be able to connect to Metis to configure it + further unless one includes at least a listener for TCP localhost or a unix domain socket. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>--capacity <replaceable class="parameter">contentStoreSize</replaceable></term> + <listitem> + <para> + Sets the capacity of the Content Store to + <replaceable class="parameter">contentStoreSize</replaceable> content objects. + Metis uses a least-recently-used eviction policy. A size of 0 will disable the + Content Store. + </para> + <para> + The Content Store sits on the fast path of the forwarder, so there is a cost + associated with adding and removing items to the Content Store tables. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>--daemon</term> + <listitem> + <para> + Runs Metis in daemon mode, detaching from the console. It must + be run with the <replaceable class="option">--log-file</replaceable> option. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>--log <replaceable class="parameter">facility</replaceable>=<replaceable class="parameter">level</replaceable></term> + <listitem> + <para> + Sets the log level of the given + <replaceable class="parameter">facility</replaceable> + to the given + <replaceable class="parameter">level</replaceable>. + The <replaceable class="option">--log</replaceable> option may be repeated + several times setting the log level of different facilities. If the same + facility is listed twice, only the last occurance takes effect. + The default log level is Error for all facilities. + </para> + + <para> + Facilities:<itemizedlist mark='opencircle'> + <listitem><para> + all: All facilities. + </para></listitem> + + <listitem><para> + config: Configuration activies. + </para></listitem> + + <listitem><para> + core: Core forwarder, such as startup and shutdown. + </para></listitem> + + <listitem><para> + io: Listeners, connections, and all I/O related activities. + </para></listitem> + + <listitem><para> + message: CCNx messages, such as parsing. + </para></listitem> + + <listitem><para> + processor: Forwarding processor, such as CS, FIB, and PIT activities. + </para></listitem> + </itemizedlist> + </para> + + <para> + The log levels are: debug, info, notice, warning, error, critical, alert, off. + </para> + + </listitem> + </varlistentry> + + <varlistentry> + <term>--log-file <replaceable class="parameter">logfile</replaceable></term> + <listitem> + <para> + Specifies the + <replaceable class="parameter">logfile</replaceable> + to write all log messages. This parameter is required with + <replaceable class="option">--daemon</replaceable> mode. + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term>--port <replaceable class="parameter">port</replaceable></term> + <listitem> + <para> + The UDP and TCP port to listen on. If no + <replaceable class="parameter">configfile</replaceable> + is specified, Metis will listen on this port on all interfaces + including localhost. + </para> + <para> + If this parameter is not given, Metis uses the default port 9695. + </para> + </listitem> + </varlistentry> + + </variablelist> +</refsect1> +<refsect1> + <title>USAGE</title> + <para> + <command>metis_daemon</command> --config metis.cfg --log all=info --log config=debug --log-file metis.log + </para> +</refsect1> + +<refsect1> + <title>SEE ALSO</title> + <para> + See <citerefentry><refentrytitle>metis_control</refentrytitle><manvolnum>1</manvolnum></citerefentry> for a + description of how to configure <command>metis_daemon</command>. + </para> + <para> + For a list of all configuration lines that may be used with + <command>metis_control</command> and by <replaceable class="option">--config</replaceable> configuration file, + see <citerefentry><refentrytitle>metis.cfg</refentrytitle><manvolnum>5</manvolnum></citerefentry>. + </para> +</refsect1> + +<refsect1> + <title>CAVEATS</title> + <itemizedlist mark='opencircle'> + <listitem><para> + A given interface may only have one Ethernet listener on one EtherType. + </para></listitem> + + <listitem><para> + If there are multiple longest matching prefix entries that match an Interest, it will be + forwarded to all those routes (i.e. multicast). + </para></listitem> + + <listitem><para> + Ethernet fragmentation will only use the interface MTU and there is not MTU discovery. If Metis is + used in a bridged environment, this may lead to errors if the MTU changes on different segments, such + as a 10G link at 9000 bytes and a 100 Mbps link at 1500 bytes. + </para></listitem> + </itemizedlist> +</refsect1> +<refsect1> + <title>BUGS</title> + <itemizedlist mark='opencircle'> + <listitem><para> + Adding the same listener twice will cause Metis to crash. + </para></listitem> + + <listitem><para> + Errors in the configuration file may cause Metis to crash. + </para></listitem> + + <listitem><para> + The command 'list connections' will display all connections as TCP encapsulation. + </para></listitem> + + </itemizedlist> + +</refsect1> +<refsect1> + <title>AUTHOR</title> + <para> + <author> + <firstname>Marc</firstname> + <surname>Mosko</surname> + <contrib>Palo Alto Research Center</contrib> + </author> + </para> +</refsect1> +</refentry> + + |