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