.\" 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 *
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.
.It *
Start an
.Tn AYIYA
responder program that will connect to the
.Nm ayiya
node's
.Va control
hook, listen for any incoming heartbeat, echo, "message of the day",
or query packets, and process them as necessary.
A sample
.Tn AYIYA
responder using the
.Nm ayiya
Netgraph node is available in the
.Nm
source directory as
.Xr ayiya_resp 8 .
.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
A hook used by userland programs to initialize and control the
.Tn AYIYA
tunnel's operation.
This hook is a suitable avenue for sending control messages to the
.Nm ayiya
node during its configuration.
It also serves another purpose: all packets that arrive from the
.Tn AYIYA
peer and are not IPv6 forwarded data packets (opcode 1) are sent
as data packets down the
.Nm ayiya
node's
.Va control
hook for the userland program to process.
Similarly, all data packets coming in via the
.Va control
hook are signed with the
.Tn AYIYA
tunnel's secret hash and sent to the
.Tn AYIYA
peer.
.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_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.
.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@FreeBSD.org