1 8d1b399b 2021-07-22 op .\" Copyright (c) 2021 Omar Polo <op@omarpolo.com>
  2 8d1b399b 2021-07-22 op .\"
  3 8d1b399b 2021-07-22 op .\" Permission to use, copy, modify, and distribute this software for any
  4 8d1b399b 2021-07-22 op .\" purpose with or without fee is hereby granted, provided that the above
  5 8d1b399b 2021-07-22 op .\" copyright notice and this permission notice appear in all copies.
  6 8d1b399b 2021-07-22 op .\"
  7 8d1b399b 2021-07-22 op .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  8 8d1b399b 2021-07-22 op .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  9 8d1b399b 2021-07-22 op .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
 10 8d1b399b 2021-07-22 op .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
 11 8d1b399b 2021-07-22 op .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
 12 8d1b399b 2021-07-22 op .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 13 8d1b399b 2021-07-22 op .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 14 8d1b399b 2021-07-22 op .\"
 15 7764059f 2021-12-14 op .Dd $Mdocdate: December 14 2021 $
 16 8d1b399b 2021-07-22 op .Dt KAMID.CONF 5
 17 8d1b399b 2021-07-22 op .Os
 18 8d1b399b 2021-07-22 op .Sh NAME
 19 8d1b399b 2021-07-22 op .Nm kamid.conf
 20 8d1b399b 2021-07-22 op .Nd 9p file server daemon configuration file
 21 8d1b399b 2021-07-22 op .Sh DESCRIPTION
 22 7764059f 2021-12-14 op .Nm
 23 7764059f 2021-12-14 op is the configuration file for the 9p file server daemon
 24 7764059f 2021-12-14 op .Xr kamid 8 .
 25 7764059f 2021-12-14 op .Pp
 26 7764059f 2021-12-14 op The format of the configuration file is fairly flexible.
 27 7764059f 2021-12-14 op The current line can be extended over multiple lines using a backslash
 28 7764059f 2021-12-14 op .Pq Sq \e .
 29 7764059f 2021-12-14 op Comments can be put anywhere in the file using a hash mark
 30 7764059f 2021-12-14 op .Pq Sq # ,
 31 7764059f 2021-12-14 op and extend to the end of the current line.
 32 7764059f 2021-12-14 op Care should be taken when commenting out multi-line text: the comment is
 33 7764059f 2021-12-14 op effective until the end of the entire block.
 34 7764059f 2021-12-14 op Arguments names not beginning with a letter, digit, or underscore, as
 35 7764059f 2021-12-14 op well as reserved words
 36 7764059f 2021-12-14 op (such as
 37 7764059f 2021-12-14 op .Ic listen ,
 38 7764059f 2021-12-14 op .Ic pki
 39 7764059f 2021-12-14 op and
 40 7764059f 2021-12-14 op .Ic table )
 41 7764059f 2021-12-14 op must be quoted.
 42 7764059f 2021-12-14 op Arguments containing whitespace should be surrounded by double quotes
 43 7764059f 2021-12-14 op .Pq \&" .
 44 7764059f 2021-12-14 op .Pp
 45 7764059f 2021-12-14 op Macros can be defined that are later expanded in context.
 46 7764059f 2021-12-14 op Macro names must start with a letter, digit, or underscore, and may
 47 7764059f 2021-12-14 op contain any of those characters, but may not be reserved words.
 48 7764059f 2021-12-14 op Macros are not expanded inside quotes.
 49 7764059f 2021-12-14 op For example:
 50 7764059f 2021-12-14 op .Bd -literal -offset indent
 51 7764059f 2021-12-14 op lan_addr = "192.168.0.1"
 52 7764059f 2021-12-14 op listen on $lan_addr
 53 7764059f 2021-12-14 op listen on $lan_addr tls auth <users>
 54 7764059f 2021-12-14 op .Ed
 55 7764059f 2021-12-14 op .Pp
 56 7764059f 2021-12-14 op Additional configuration files can be included with the
 57 7764059f 2021-12-14 op .Ic include
 58 7764059f 2021-12-14 op keyword, for example:
 59 7764059f 2021-12-14 op .Bd -literal -offset indent
 60 7764059f 2021-12-14 op include "/etc/kamid.conf.local"
 61 7764059f 2021-12-14 op .Ed
 62 7764059f 2021-12-14 op .Pp
 63 7764059f 2021-12-14 op The syntax of
 64 7764059f 2021-12-14 op .Nm
 65 7764059f 2021-12-14 op is described below.
 66 7764059f 2021-12-14 op .Bl -tag -width Ds
 67 7764059f 2021-12-14 op .It Ic listen Op Ar options...
 68 7764059f 2021-12-14 op The options are as follows:
 69 7764059f 2021-12-14 op .Bl -tag -width Ds
 70 7764059f 2021-12-14 op .It Ic on Ar address Ic port Ar number
 71 7764059f 2021-12-14 op Listen on the
 72 7764059f 2021-12-14 op .Ar address
 73 7764059f 2021-12-14 op for incoming connection on the given port
 74 7764059f 2021-12-14 op .Ar number .
 75 7764059f 2021-12-14 op .Ar address
 76 7764059f 2021-12-14 op can be an IP address or a domain name.
 77 7764059f 2021-12-14 op .It Ic tls Ic pki Ar name
 78 7764059f 2021-12-14 op Use the tls certificate
 79 7764059f 2021-12-14 op .Ar name
 80 7764059f 2021-12-14 op previously defined with the
 81 7764059f 2021-12-14 op .Ic pki
 82 7764059f 2021-12-14 op rule.
 83 7764059f 2021-12-14 op .It Ic auth Pf < Ar table Ns >
 84 7764059f 2021-12-14 op Use the given authentication
 85 7764059f 2021-12-14 op .Ar table
 86 7764059f 2021-12-14 op to authorize the clients.
 87 c35679af 2021-12-18 op .It Ic userdata Pf < Ar table Ns >
 88 c35679af 2021-12-18 op Maps user
 89 c35679af 2021-12-18 op .Pq virtuals or not
 90 c35679af 2021-12-18 op to their exported tree.
 91 c35679af 2021-12-18 op By default the user home directory obtained with
 92 c35679af 2021-12-18 op .Xr getpwnam 3
 93 c35679af 2021-12-18 op is used.
 94 c35679af 2021-12-18 op .It Ic virtual Pf < Ar table Ns >
 95 c35679af 2021-12-18 op Maps virtual users to local user.
 96 7764059f 2021-12-14 op .El
 97 7764059f 2021-12-14 op .It Ic pki Ar pkiname Ic cert Ar certfile
 98 7764059f 2021-12-14 op Associate certificate file
 99 7764059f 2021-12-14 op .Ar certfile
100 7764059f 2021-12-14 op with pki entry
101 7764059f 2021-12-14 op .Ar pkiname .
102 7764059f 2021-12-14 op The pki entry defines a keypair configuration that can be referenced in
103 7764059f 2021-12-14 op listener rules.
104 7764059f 2021-12-14 op .It Ic pki Ar pkiname Ic key Ar keyfile
105 7764059f 2021-12-14 op Associate the key located in
106 7764059f 2021-12-14 op .Ar keyfile
107 7764059f 2021-12-14 op with pki entry
108 7764059f 2021-12-14 op .Ar pkiname .
109 7764059f 2021-12-14 op .\" TODO: document the other syntax for the table
110 7764059f 2021-12-14 op .It Ic table Ar name Brq Ar value Cm => Ar value Oo , Ar ... Oc
111 7764059f 2021-12-14 op Tables provide additional configuration information for
112 8d1b399b 2021-07-22 op .Xr kamid 8
113 7764059f 2021-12-14 op in the form of key-value mappings.
114 7764059f 2021-12-14 op .Pp
115 7764059f 2021-12-14 op Declare a mapping table containing the given static
116 7764059f 2021-12-14 op .Ar key Ns Pf - Ar value
117 7764059f 2021-12-14 op pairs.
118 7764059f 2021-12-14 op .El
119 7764059f 2021-12-14 op .Sh EXAMPLES
120 7764059f 2021-12-14 op A sample configuration file:
121 7764059f 2021-12-14 op .Bd -literal -offset indent
122 7764059f 2021-12-14 op pki localhost cert "/etc/ssl/localhost.crt"
123 7764059f 2021-12-14 op pki localhost key "/etc/ssl/private/localhost.key"
124 7764059f 2021-12-14 op 
125 7764059f 2021-12-14 op table users { "SHA256:..." => "op" }
126 7764059f 2021-12-14 op 
127 7764059f 2021-12-14 op listen on localhost port 1337 tls pki localhost auth <users>
128 7764059f 2021-12-14 op .Ed
129 8d1b399b 2021-07-22 op .Sh SEE ALSO
130 8d1b399b 2021-07-22 op .Xr kamictl 8 ,
131 8d1b399b 2021-07-22 op .Xr kamid 8