man/dnstt-server.1

   1 .\" https://man.openbsd.org/mdoc.7
   2 .Dd 2020-08-30
   3 .Dt DNSTT-SERVER 1
   4 .Os
   5
   6
   7 .Sh NAME
   8
   9 .Nm dnstt-server
  10 .Nd DNS tunnel server
  11
  12
  13 .Sh SYNOPSIS
  14
  15 .Nm
  16 .Fl gen-key
  17 .Op Fl privkey-file Ar FILENAME
  18 .Op Fl pubkey-file Ar FILENAME
  19
  20 .Nm
  21 .Fl udp Ar ADDR : Ns Ar PORT
  22 .Op Fl privkey Ar HEX | Fl privkey-file Ar FILENAME
  23 .Op Fl mtu Ar MTU
  24 .Ar DOMAIN
  25 .Ar UPSTREAMADDR : Ns Ar UPSTREAMPORT
  26
  27
  28 .Sh DESCRIPTION
  29
  30 .Nm
  31 is the server portion of a DNS tunnel.
  32 It receives DNS over UDP messages at
  33 .Ar ADDR : Ns Ar PORT ,
  34 decodes the streams they contain,
  35 and forwards the streams as TCP connections to
  36 .Ar UPSTREAMADDR : Ns Ar UPSTREAMPORT .
  37 .Nm acts as the authoritative name server for
  38 .Ar DOMAIN
  39 and communicates with an instance of
  40 .Xr dnstt-client 1
  41 via a recursive resolver.
  42
  43 .Ss GENERATING A SERVER KEYPAIR
  44
  45 The tunnel client
  46 encrypts and authenticates the tunneled connection
  47 using the server's public key.
  48 To generate a server keypair, use the
  49 .Fl gen-key
  50 option.
  51 Use the
  52 .Fl privkey-file
  53 and
  54 .Fl pubkey-file
  55 options to save the generated private key,
  56 public key, or both,
  57 to a file.
  58
  59 .Bl -tag
  60
  61 .It Fl gen-key
  62 Generate a server keypair.
  63
  64 .It Fl privkey-file Ar FILENAME
  65 With
  66 .Fl gen-key ,
  67 save the generated private key to
  68 .Ar FILENAME .
  69
  70 .It Fl pubkey-file Ar FILENAME
  71 With
  72 .Fl gen-key ,
  73 save the generated public key to
  74 .Ar FILENAME .
  75
  76 .El
  77
  78 .Pp
  79 On the server, you only need to store the private key, because
  80 .Nm
  81 can derive the public key from the private key.
  82 The client only needs to have the server's public key
  83 and should not know the servers private key.
  84
  85 .Ss RUNNING THE SERVER
  86
  87 The required
  88 .Fl udp
  89 option specifies the UDP address on which
  90 .Nm
  91 listens for incoming DNS messages.
  92
  93 .Bl -tag
  94 .It Fl udp Ar ADDR : Ns Ar PORT
  95 Accept DNS messages at the given address.
  96 .Ar PORT
  97 must typically be 53
  98 when operating with a recursive intermediate resolver,
  99 unless you have made some other provision for forwarding
 100 port 53 to
 101 .Ar PORT .
 102
 103 .El
 104
 105 .Pp
 106 Specify the server's persistent keypair using the
 107 .Fl privkey
 108 or
 109 .Fl privkey-file
 110 options.
 111 If you do not use one of these options,
 112 .Nm
 113 generates a temporary keypair
 114 and logs the public key to standard error.
 115
 116 .Bl -tag
 117
 118 .It Fl privkey Ar HEX
 119 .Ar HEX
 120 is a string of 64 hexadecimal digits.
 121
 122 .It Fl privkey-file Ar FILENAME
 123 .Ar FILENAME
 124 is the name of a file containing
 125 64 hexadecimal digits and an
 126 optional training newline character.
 127
 128 .El
 129
 130 .Pp
 131 In some situations, you may have to use the
 132 .Fl mtu
 133 option to control the maximum UDP payload size.
 134
 135 .Bl -tag
 136
 137 .It Fl mtu Ar MTU
 138 Never send UDP payloads larger than
 139 .Ar MTU
 140 bytes.
 141 The default
 142 .Ar MTU
 143 is 1232, but some recursive resolver only support a maximum of 512.
 144 You will know you need to use the
 145 .Fl mtu
 146 option when you see messages like this on standard error:
 147 .Dl FORMERR: requester payload size 512 is too small (minimum 1232)
 148
 149 .El
 150
 151
 152 .Sh EXAMPLES
 153
 154 Generate a keypair.
 155 Save the private key to the file
 156 .Cm server.key
 157 and the public key to
 158 .Cm server.pub .
 159 Next, you would typically copy
 160 .Pa server.pub
 161 to the client.
 162
 163 .Bd -literal -offset indent
 164 dnstt-server -gen-key -privkey-file server.key -pubkey-file server.pub
 165 .Ed
 166
 167 .Pp
 168 Accept DNS messages at the UDP address
 169 .Cm 0.0.0.0:53 ,
 170 decode the streams contained therein,
 171 and forward the streams as TCP connections to
 172 .Cm 127.0.0.1:8000 .
 173 Read the private key from the file
 174 .Cm server.key
 175 and derive the public key from it.
 176 The server should be configured to be
 177 the authoritative name server for the domain
 178 .Cm t.example.com .
 179
 180 .Bd -literal -offset indent
 181 dnstt-server -udp 127.0.0.1:53 -privkey-file server.key t.example.com 127.0.0.1:8000
 182 .Ed
 183
 184
 185 .Sh DIAGNOSTICS
 186
 187 .Nm
 188 writes running logs to standard error.
 189
 190 At startup,
 191 .Nm
 192 logs its public key.
 193 This string can be used with the
 194 .Fl -pubkey
 195 option in
 196 .Xr dnstt-client 1 .
 197
 198 .Dl pubkey 14ca15f53660e248d289d9302f992c4bee518f2361d6343dafa7b417b5a3d752
 199
 200 .Pp
 201 At startup,
 202 .Nm
 203 logs the amount of useful payload capacity that can be stored
 204 in each DNS response, after accounting for the overhead of encoding.
 205 This number will vary depending on the length of
 206 .Ar DOMAIN
 207 and the value of
 208 .Ar MTU .
 209
 210 .Dl effective MTU 932
 211
 212
 213 .Pp
 214 If the recursive resolver's stated maximum UDP payload size
 215 is smaller than
 216 .Ar MTU ,
 217 .Nm
 218 will log a message like this,
 219 which tells you that you need to use the
 220 .Fl mtu
 221 option.
 222
 223 .Dl FORMERR: requester payload size 512 is too small (minimum 1232)
 224
 225
 226 .Sh SEE ALSO
 227
 228 .Xr dnstt-client 1
 229
 230 .Lk https://www.bamsoftware.com/software/dnstt/
 231
 232
 233 .Sh AUTHORS
 234
 235 .An David Fifield Aq Mt david@bamsoftware.com