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 December 7, 2012
  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         int     dom_rtoffset;           /* an arg to rtattach, in bits */
  86         int     dom_maxrtkey;           /* for routing layer */
  87         void    *(*dom_ifattach)(struct ifnet *);
  88         void    (*dom_ifdetach)(struct ifnet *, void *);
  89                                         /* af-dependent data on ifnet */
  90 };
  91 .Ed
  92 .Pp
  93 Each domain contains an array of protocol switch structures
  94 .Pq Vt "struct protosw *" ,
  95 one for each socket type supported.
  96 .Bd -literal
  97 struct protosw {
  98         short   pr_type;                /* socket type used for */
  99         struct  domain *pr_domain;      /* domain protocol a member of */
 100         short   pr_protocol;            /* protocol number */
 101         short   pr_flags;               /* see below */
 102 /* protocol-protocol hooks */
 103         pr_input_t *pr_input;           /* input to protocol (from below) */
 104         pr_output_t *pr_output;         /* output to protocol (from above) */
 105         pr_ctlinput_t *pr_ctlinput;     /* control input (from below) */
 106         pr_ctloutput_t *pr_ctloutput;   /* control output (from above) */
 107 /* utility hooks */
 108         pr_init_t *pr_init;
 109         pr_destroy_t *pr_destroy;
 110         pr_fasttimo_t *pr_fasttimo;     /* fast timeout (200ms) */
 111         pr_slowtimo_t *pr_slowtimo;     /* slow timeout (500ms) */
 112         pr_drain_t *pr_drain;           /* flush any excess space possible */
 113
 114         struct  pr_usrreqs *pr_usrreqs; /* supersedes pr_usrreq() */
 115 };
 116 .Ed
 117 .Pp
 118 The following functions handle the registration of a new domain,
 119 lookups of specific protocols and protocol types within those domains,
 120 and handle control messages from the system.
 121 .Pp
 122 .Fn pfctlinput
 123 is called by the system whenever an event occurs that could affect every
 124 domain.
 125 Examples of those types of events are routing table changes, interface
 126 shutdowns or certain
 127 .Tn ICMP
 128 message types.
 129 When called,
 130 .Fn pfctlinput
 131 calls the protocol specific
 132 .Fn pr_ctlinput
 133 function for each protocol in that has defined one, in every domain.
 134 .Pp
 135 .Fn pfctlinput2
 136 provides that same functionality of
 137 .Fn pfctlinput ,
 138 but with a few additional checks and a new
 139 .Vt "void *"
 140 argument that is passed directly to the protocol's
 141 .Fn pr_ctlinput
 142 function.
 143 Unlike
 144 .Fn pfctlinput ,
 145 .Fn pfctlinput2
 146 verifies that
 147 .Fa sa
 148 is not
 149 .Dv NULL ,
 150 and that only the protocol families that are the same as
 151 .Fa sa
 152 have their
 153 .Fn pr_ctlinput
 154 function called.
 155 .Pp
 156 .Fn domain_add
 157 adds a new protocol domain to the system.
 158 The argument
 159 .Fa data
 160 is cast directly to
 161 .Vt "struct domain *"
 162 within the function, but is declared
 163 .Vt "void *"
 164 in order to prevent compiler warnings when new domains are registered with
 165 .Fn SYSINIT .
 166 In most cases
 167 .Fn domain_add
 168 is not called directly, instead
 169 .Fn DOMAIN_SET
 170 is used.
 171 .Pp
 172 If the new domain has defined an initialization routine, it is called by
 173 .Fn domain_add ;
 174 as well, each of the protocols within the domain that have defined an
 175 initialization routine will have theirs called.
 176 .Pp
 177 Once a domain is added it cannot be unloaded.
 178 This is because there is
 179 no reference counting system in place to determine if there are any
 180 active references from sockets within that domain.
 181 .Pp
 182 .Fn pffinddomain
 183 finds a domain by family.
 184 If the domain cannot be found,
 185 .Dv NULL
 186 is returned.
 187 .Pp
 188 .Fn pffindtype
 189 and
 190 .Fn pffindproto
 191 look up a protocol by its number or by its type.
 192 In most cases, if the protocol or type cannot be found,
 193 .Dv NULL
 194 is returned, but
 195 .Fn pffindproto
 196 may return the default if the requested type is
 197 .Dv SOCK_RAW ,
 198 a protocol switch type of
 199 .Dv SOCK_RAW
 200 is found, and the domain has a default raw protocol.
 201 .Pp
 202 Both functions are called by
 203 .Fn socreate
 204 in order to resolve the protocol for the socket currently being created.
 205 .Pp
 206 .Fn DOMAIN_SET
 207 is a macro that simplifies the registration of a domain via
 208 .Fn SYSINIT .
 209 The code resulting from the macro expects there to be a domain structure
 210 named
 211 .Dq Fa name Ns Li domain
 212 where
 213 .Fa name
 214 is the argument to
 215 .Fn DOMAIN_SET :
 216 .Bd -literal
 217 struct domain localdomain =
 218 { AF_LOCAL, "local", unp_init, unp_externalize, unp_dispose,
 219   localsw, &localsw[sizeof(localsw)/sizeof(localsw[0])] };
 220
 221 DOMAIN_SET(local);
 222 .Ed
 223 .Sh RETURN VALUES
 224 Both
 225 .Fn pffindtype
 226 and
 227 .Fn pffindproto
 228 return a
 229 .Vt "struct protosw *"
 230 for the protocol requested.
 231 If the protocol or socket type is not found,
 232 .Dv NULL
 233 is returned.
 234 In the case of
 235 .Fn pffindproto ,
 236 the default protocol may be returned for
 237 .Dv SOCK_RAW
 238 types if the domain has a default raw protocol.
 239 .Sh SEE ALSO
 240 .Xr socket 2
 241 .Sh AUTHORS
 242 This manual page was written by
 243 .An Chad David Aq davidc@acns.ab.ca .