socsvn commit: r287683 - soc2015/roam/ng_ayiya

Sun Jun 28 01:39:35 UTC 2015

Author: roam
Date: Sun Jun 28 01:39:33 2015
New Revision: 287683
URL: http://svnweb.FreeBSD.org/socsvn/?view=rev&rev=287683

Log:
  Add a ng_ayiya(4) manual page.
  
  Regrettably, it is not automatically installed yet.
  
  ObQuote:	"Listen, learn, read on"

Added:
  soc2015/roam/ng_ayiya/ng_ayiya.4

Added: soc2015/roam/ng_ayiya/ng_ayiya.4
==============================================================================

--- /dev/null	00:00:00 1970	(empty, because file is newly added)
+++ soc2015/roam/ng_ayiya/ng_ayiya.4	Sun Jun 28 01:39:33 2015	(r287683)
@@ -0,0 +1,227 @@
+.\" Copyright (c) 2015  Peter Pentchev
+.\" All rights reserved.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+.\" SUCH DAMAGE.
+.\"
+.Dd June 24, 2015
+.Dt NG_AYIYA 4
+.Os
+.Sh NAME
+.Nm ng_ayiya
+.Nd Anything-In-Anything tunnel node type
+.Sh SYNOPSIS
+.In netgraph/ng_ayiya.h
+.Sh DESCRIPTION
+An
+.Nm ayiya
+node maintains an
+.Dq Anything-In-Anything
+.Pq Tn AYIYA
+tunnel between a local IPv6 interface and a remote
+.Tn AYIYA
+server (e.g. a
+.Tn SixXS
+IPv6 tunnel).
+It encapsulates packets going out of the local IPv6 interface into
+.Tn AYIYA
+packets and sends them to the remote server, then decodes packets
+received from the latter and sends them to the IPv6 interface as
+incoming packets.
+.Pp
+An
+.Nm ayiya
+node has at least two hooks during normal operation: a
+.Va inet6
+or
+.Va inet6/*
+one to the
+.Xr ng_iface 4
+node corresponding to the local IPv6 interface, and a
+.Va ayiya
+or
+.Va ayiya/*
+one to the
+.Xr ng_ksocket 4
+node connected to the remote
+.Tn AYIYA
+server.
+It also accepts a third hook named
+.Va control
+for management and configuration purposes; any data coming in
+via that hook is ignored.
+.Pp
+Setting up an
+.Nm ayiya
+node usually involves the following steps:
+.Bl -tag -width "*"
+.It *
+Create the
+.Nm ayiya
+node, possibly through setting up a
+.Va control
+hook to a
+.Nm socket
+node.
+.It *
+Configure the tunnel by sending a
+.Dv NGM_AYIYA_SECRETHASH
+control message to set the secret hash used for authentication of the
+.Tn AYIYA
+packets.
+.It *
+Configure the node by sending a
+.Dv NGM_AYIYA_SET_VERSION
+and optionally a
+.Dv NGM_AYIYA_SET_MOTD
+control message.
+.It *
+Connect the
+.Va inet6
+hook to a
+.Xr ng_iface 4
+Netgraph node that will serve as the local IPv6 interface.
+.It *
+Set up the IPv6 address of the
+.Xr ng_iface 4
+node, e.g. with information obtained via the
+.Tn TIC
+protocol negotiation that also supplied the secret hash.
+.It *
+Connect the
+.Va ayiya
+hook to a
+.Xr ng_ksocket 4
+Netgraph node that will provide the connection to the
+.Tn AYIYA
+server; usually the connection is made to the
+.Xr ng_ksocket 4
+node's
+.Va inet/dgram/udp
+hook.
+.It *
+Connect the
+.Xr ng_ksocket 4
+node to the
+.Tn AYIYA
+server.
+.It *
+Activate the
+.Nm ayiya
+node by sending it the
+.Dv NGM_AYIYA_CONFIGURE
+control message; when the message has been processed, the tunnel
+should be up and running.
+.El
+.Sh HOOKS
+The
+.Nm ayiya
+node supports the following hooks:
+.Bl -tag -width "control"
+.It Va ayiya
+The actual connection to the
+.Tn AYIYA
+server; typically connected to the
+.Dv inet/dgram/udp
+hook of a
+.Xr ng_ksocket 4
+node.
+This hook may also be named
+.Va ayiya/*
+for the administrator's convenience; any text after the slash is
+ignored.
+.It Va control
+Control messages only, any data packets are ignored.
+.It Va inet6
+The local IPv6 interface, a
+.Xr ng_iface 4
+node with at least one non-local-scoped IPv6 address at the time the
+.Dv NGM_AYIYA_CONFIGURE
+control message is processed.
+This hook may also be named
+.Va inet6/*
+for the administrator's convenience; any text after the slash is
+ignored.
+.El
+.Sh CONTROL MESSAGES
+The
+.Nm ayiya
+node supports the generic control messages; it provides a human-readable
+status description as a reply to a
+.Dv NGM_TEXT_STATUS
+control message and a JSON status description as a reply to a
+.Dv NGM_TEXT_CONFIG
+control message.
+It also supports the following control messages:
+.Bl -tag -width "NGM_AYIYA_GET_VERSION"
+.It Dv NGM_AYIYA_CONFIGURE
+Commence operations: obtain the local IPv6 address from the
+.Xr ng_iface 4
+node connected to the
+.Va inet6
+hook, then send an
+.Tn AYIYA
+heartbeat packet to the
+.Va ayiya
+hook and start forwarding packets between the two.
+.It Dv NGM_AYIYA_GET_VERSION
+Get the local
+.Nm ayiya
+node's version string.
+.It Dv NGM_AYIYA_GET_MOTD
+Get the local
+.Nm ayiya
+node's
+.Dq message of the day
+string.
+.It Dv NGM_AYIYA_SECRETHASH
+Set the secret hash used for authenticating the
+.Tn AYIYA
+packets.
+The message parameter should be a SHA1 hash of the
+.Va Password
+field obtained via TIC negotiation.
+.It Dv NGM_AYIYA_SET_VERSION
+Set the local
+.Nm ayiya
+node's version string.
+.It Dv NGM_AYIYA_SET_MOTD
+Set the local
+.Nm ayiya
+node's
+.Dq message of the day
+string.
+.El
+.Sh SHUTDOWN
+This node shuts down upon receipt of a
+.Dv NGM_SHUTDOWN
+control message.
+.Sh SEE ALSO
+.Xr netgraph 4 ,
+.Xr ng_iface 4 ,
+.Xr ng_ksocket 4 ,
+.Xr ngctl 8
+.Sh HISTORY
+The
+.Nm ayiya
+node type was developed by Peter Pentchev.
+.Sh AUTHORS
+.An Peter Pentchev Aq Mt roam at FreeBSD.org
