share/man/man9/domain.9

   1 .\"
   2 .\" Copyright (C) 2001 Chad David <davidc@acns.ab.ca>. All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice(s), this list of conditions and the following disclaimer as
   9 .\"    the first lines of this file unmodified other than the possible
  10 .\"    addition of one or more copyright notices.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice(s), this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\"
  15 .\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY
  16 .\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  17 .\" WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
  18 .\" DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE LIABLE FOR ANY
  19 .\" DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
  20 .\" (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
  21 .\" SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
  22 .\" CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  23 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  24 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH
  25 .\" DAMAGE.
  26 .\"
  27 .\" $FreeBSD$
  28 .\"
  29 .Dd November 6, 2014
  30 .Dt DOMAIN 9
  31 .Os
  32 .Sh NAME
  33 .Nm domain_add ,
  34 .Nm pfctlinput ,
  35 .Nm pfctlinput2 ,
  36 .Nm pffinddomain ,
  37 .Nm pffindproto ,
  38 .Nm pffindtype ,
  39 .Nm DOMAIN_SET
  40 .Nd "network domain management"
  41 .Sh SYNOPSIS
  42 .In sys/param.h
  43 .In sys/kernel.h
  44 .In sys/protosw.h
  45 .In sys/domain.h
  46 .Ft void
  47 .Fn domain_add "void *data"
  48 .Ft void
  49 .Fn pfctlinput "int cmd" "struct sockaddr *sa"
  50 .Ft void
  51 .Fn pfctlinput2 "int cmd" "struct sockaddr *sa" "void *ctlparam"
  52 .Ft struct domain *
  53 .Fn pffinddomain "int family"
  54 .Ft struct protosw *
  55 .Fn pffindproto "int family" "int protocol" "int type"
  56 .Ft struct protosw *
  57 .Fn pffindtype "int family" "int type"
  58 .Ft void
  59 .Fn DOMAIN_SET "name"
  60 .Sh DESCRIPTION
  61 Network protocols installed in the system are maintained within what
  62 are called domains
  63 (for example the
  64 .Va inetdomain
  65 and
  66 .Va localdomain ) .
  67 .Bd -literal
  68 struct domain {
  69         int     dom_family;             /* AF_xxx */
  70         char    *dom_name;
  71         void    (*dom_init)             /* initialize domain data structures */
  72                 (void);
  73         void    (*dom_destroy)          /* cleanup structures / state */
  74                 (void);
  75         int     (*dom_externalize)      /* externalize access rights */
  76                 (struct mbuf *, struct mbuf **);
  77         void    (*dom_dispose)          /* dispose of internalized rights */
  78                 (struct mbuf *);
  79         struct  protosw *dom_protosw, *dom_protoswNPROTOSW;
  80         struct  domain *dom_next;
  81         int     (*dom_rtattach)         /* initialize routing table */
  82                 (void **, int);
  83         int     (*dom_rtdetach)         /* clean up routing table */
  84                 (void **, int);
  85         void    *(*dom_ifattach)(struct ifnet *);
  86         void    (*dom_ifdetach)(struct ifnet *, void *);
  87         int     (*dom_ifmtu)(struct ifnet *);
  88                                         /* af-dependent data on ifnet */
  89 };
  90 .Ed
  91 .Pp
  92 Each domain contains an array of protocol switch structures
  93 .Pq Vt "struct protosw *" ,
  94 one for each socket type supported.
  95 .Bd -literal
  96 struct protosw {
  97         short   pr_type;                /* socket type used for */
  98         struct  domain *pr_domain;      /* domain protocol a member of */
  99         short   pr_protocol;            /* protocol number */
 100         short   pr_flags;               /* see below */
 101 /* protocol-protocol hooks */
 102         pr_input_t *pr_input;           /* input to protocol (from below) */
 103         pr_output_t *pr_output;         /* output to protocol (from above) */
 104         pr_ctlinput_t *pr_ctlinput;     /* control input (from below) */
 105         pr_ctloutput_t *pr_ctloutput;   /* control output (from above) */
 106 /* utility hooks */
 107         pr_init_t *pr_init;
 108         pr_destroy_t *pr_destroy;
 109         pr_fasttimo_t *pr_fasttimo;     /* fast timeout (200ms) */
 110         pr_slowtimo_t *pr_slowtimo;     /* slow timeout (500ms) */
 111         pr_drain_t *pr_drain;           /* flush any excess space possible */
 112
 113         struct  pr_usrreqs *pr_usrreqs; /* user-protocol hook */
 114 };
 115 .Ed
 116 .Pp
 117 The following functions handle the registration of a new domain,
 118 lookups of specific protocols and protocol types within those domains,
 119 and handle control messages from the system.
 120 .Pp
 121 .Fn pfctlinput
 122 is called by the system whenever an event occurs that could affect every
 123 domain.
 124 Examples of those types of events are routing table changes, interface
 125 shutdowns or certain
 126 .Tn ICMP
 127 message types.
 128 When called,
 129 .Fn pfctlinput
 130 calls the protocol specific
 131 .Fn pr_ctlinput
 132 function for each protocol in that has defined one, in every domain.
 133 .Pp
 134 .Fn pfctlinput2
 135 provides that same functionality of
 136 .Fn pfctlinput ,
 137 but with a few additional checks and a new
 138 .Vt "void *"
 139 argument that is passed directly to the protocol's
 140 .Fn pr_ctlinput
 141 function.
 142 Unlike
 143 .Fn pfctlinput ,
 144 .Fn pfctlinput2
 145 verifies that
 146 .Fa sa
 147 is not
 148 .Dv NULL ,
 149 and that only the protocol families that are the same as
 150 .Fa sa
 151 have their
 152 .Fn pr_ctlinput
 153 function called.
 154 .Pp
 155 .Fn domain_add
 156 adds a new protocol domain to the system.
 157 The argument
 158 .Fa data
 159 is cast directly to
 160 .Vt "struct domain *"
 161 within the function, but is declared
 162 .Vt "void *"
 163 in order to prevent compiler warnings when new domains are registered with
 164 .Fn SYSINIT .
 165 In most cases
 166 .Fn domain_add
 167 is not called directly, instead
 168 .Fn DOMAIN_SET
 169 is used.
 170 .Pp
 171 If the new domain has defined an initialization routine, it is called by
 172 .Fn domain_add ;
 173 as well, each of the protocols within the domain that have defined an
 174 initialization routine will have theirs called.
 175 .Pp
 176 Once a domain is added it cannot be unloaded.
 177 This is because there is
 178 no reference counting system in place to determine if there are any
 179 active references from sockets within that domain.
 180 .Pp
 181 .Fn pffinddomain
 182 finds a domain by family.
 183 If the domain cannot be found,
 184 .Dv NULL
 185 is returned.
 186 .Pp
 187 .Fn pffindtype
 188 and
 189 .Fn pffindproto
 190 look up a protocol by its number or by its type.
 191 In most cases, if the protocol or type cannot be found,
 192 .Dv NULL
 193 is returned, but
 194 .Fn pffindproto
 195 may return the default if the requested type is
 196 .Dv SOCK_RAW ,
 197 a protocol switch type of
 198 .Dv SOCK_RAW
 199 is found, and the domain has a default raw protocol.
 200 .Pp
 201 Both functions are called by
 202 .Fn socreate
 203 in order to resolve the protocol for the socket currently being created.
 204 .Pp
 205 .Fn DOMAIN_SET
 206 is a macro that simplifies the registration of a domain via
 207 .Fn SYSINIT .
 208 The code resulting from the macro expects there to be a domain structure
 209 named
 210 .Dq Fa name Ns Li domain
 211 where
 212 .Fa name
 213 is the argument to
 214 .Fn DOMAIN_SET :
 215 .Bd -literal
 216 struct domain localdomain =
 217 { AF_LOCAL, "local", unp_init, unp_externalize, unp_dispose,
 218   localsw, &localsw[sizeof(localsw)/sizeof(localsw[0])] };
 219
 220 DOMAIN_SET(local);
 221 .Ed
 222 .Sh RETURN VALUES
 223 Both
 224 .Fn pffindtype
 225 and
 226 .Fn pffindproto
 227 return a
 228 .Vt "struct protosw *"
 229 for the protocol requested.
 230 If the protocol or socket type is not found,
 231 .Dv NULL
 232 is returned.
 233 In the case of
 234 .Fn pffindproto ,
 235 the default protocol may be returned for
 236 .Dv SOCK_RAW
 237 types if the domain has a default raw protocol.
 238 .Sh SEE ALSO
 239 .Xr socket 2
 240 .Sh AUTHORS
 241 This manual page was written by
 242 .An Chad David Aq Mt davidc@acns.ab.ca .