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