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