net/stone/files/stone.1

   1 .\" Roff format skeleton provided by Taketo Kabe <kabe@sra-tohoku.co.jp>
   2 .TH stone 1 "version 2.3e"
   3 .
   4 .SH NAME
   5 stone \- Simple Repeater
   6 .
   7 .SH SYNOPSIS
   8 .B "stone [-C \fIfile\fP] [-P \fIcommand\fP] [-Q \fIoptions\fP] [-N] [-d] [-p] [-n]"
   9 .br
  10 .B "      [-u \fImax\fP] [-f \fIn\fP] [-l] [-L \fIfile\fP] [-a \fIfile\fP] [-i \fIfile\fP]"
  11 .br
  12 .B "      [-X \fIn\fP] [-T \fIn\fP] [-A <n>] [-r]"
  13 .br
  14 .B "      [-x \fIport\fP[,\fIport\fP][-\fIport\fP]... \fIxhost\fP... --]"
  15 .br
  16 .B "      [-s \fIsend\fP \fIexpect\fP... --]"
  17 .br
  18 .B "      [-b [\fIvar\fP=\fIval\fP]... \fIn\fP \fImaster\fP:\fIport\fP \fIbackup\fP:\fIport\fP]"
  19 .br
  20 .B "      [-B \fIhost\fP:\fIport\fP \fIhost1\fP:\fIport1\fP... --]"
  21 .br
  22 .B "      [-I \fIhost\fP]"
  23 .br
  24 .B "      [-o \fIn\fP] [-g \fIn\fP] [-t \fIdir\fP] [-D] [-c \fIdir\fP]"
  25 .br
  26 .B "      [-q \fISSL\fP] [-z \fISSL\fP]"
  27 .br
  28 .B "      [-M install \fIname\fP] [-M remove \fIname\fP]"
  29 .br
  30 .B "      \fIst\fP [-- \fIst\fP]..."
  31 .
  32 .SH DESCRIPTION
  33 \fBStone\fP is a TCP & UDP repeater in the application layer.  It repeats TCP
  34 and UDP from inside to outside of a firewall, or from outside to inside.
  35 .P
  36 \fBStone\fP has following features:
  37 .
  38 .TP
  39 .B 1. Stone supports Win32.
  40 Formerly, UNIX machines are used as firewalls, but recently
  41 WindowsNT machines are used, too.  You can easily run \fBstone\fP on
  42 WindowsNT and Windows95.  Of course, available on Linux,
  43 FreeBSD, BSD/OS, SunOS, Solaris, HP-UX and so on.
  44 .
  45 .TP
  46 .B 2. Simple.
  47 \fBStone\fP's source code is only 10000 lines long (written in C
  48 language), so you can minimize the risk of security
  49 holes.
  50 .
  51 .TP
  52 .B 3. Stone supports SSL.
  53 Using OpenSSL (\fIhttp://www.openssl.org/\fP), \fBstone\fP can
  54 encrypt/decrypt.  Client verifications, and server verifications
  55 are also supported.  \fBStone\fP can send a substring of the subject
  56 of the certificate to the destination.
  57 .
  58 .TP
  59 .B 4. Stone is a http proxy.
  60 \fBStone\fP can also be a tiny http proxy.
  61 .
  62 .TP
  63 .B 5. POP -> APOP conversion.
  64 With \fBstone\fP and a mailer that does not support APOP, you can
  65 access to an APOP server.
  66 .
  67 .TP
  68 .B 6. Stone supports IPv6.
  69 \fBStone\fP can convert IP and IPv6 each other.  With \fBstone\fP, you can
  70 use IP-only software on IPv6 network.
  71 .
  72 .SH OPTIONS
  73 If the \fB-C\fP \fIfile\fP flag is used, the program read these
  74 options and \fIst\fPs from the configuration file \fIfile\fP.
  75 If the \fB-P\fP \fIcommand\fP flag is used, the program executes
  76 specified pre-processor to read the configuration file.  \fB-Q\fP \fIoptions\fP
  77 can be used to pass options to the pre-processor.  If the \fB-N\fP
  78 flag is used, \fBstone\fP will terminate after parsing options
  79 and configuration file without opening the ports.
  80 .P
  81 If the \fB-d\fP flag is used, then increase the debug level.  If
  82 the \fB-p\fP flag is used, data repeated by \fBstone\fP are dumped.  If
  83 the \fB-n\fP is used, IP addresses and service port numbers are
  84 shown instead of host names and service names.
  85 .P
  86 If the \fB-u\fP \fImax\fP flag (\fImax\fP is integer) is used, the
  87 program memorize \fImax\fP UDP sources simultaneously.  The default value
  88 is 100. If the
  89 \fB-f\fP \fIn\fP flag (\fIn\fP is integer) is used, the program spawn
  90 \fIn\fP child processes. The default behavior is not to spawn any child processes.
  91 .P
  92 If the \fB-l\fP flag is used, the program sends error messages to
  93 the syslog instead of stderr.  If the \fB-L\fP \fIfile\fP (\fIfile\fP
  94 is a file name) flag is used, the program writes error messages
  95 to the file.  If the \fB-a\fP \fIfile\fP flag is used, the program
  96 writes accounting to the file.  If the \fB-i\fP \fIfile\fP flag is
  97 used, the program writes its process ID to the file.
  98 .P
  99 The \fB-X\fP \fIn\fP flag alters the buffer size of the repeater.
 100 The default value is 1000 bytes. If
 101 the \fB-T\fP \fIn\fP is used, the timeout of TCP sessions can be
 102 specified to \fIn\fP sec.  Default: 600 (10 min).
 103 The \fB-A\fP flag specifies the maximum length the
 104 queue of pending connections may grow to.  Default: 50.
 105 The \fB-r\fP flag is used, SO_REUSEADDR is set on the socket of \fIst\fP.
 106 .P
 107 Using the \fB-x\fP \fIport\fP[,\fIport\fP][-\fIport\fP]... \fIxhost\fP... \fB--\FP flag,
 108 the http proxy (described later) can only connect to
 109 \fIxhost\fP:\fIport\fP.  If more than one \fB-x\fP ... \fB--\fI flags are
 110 designated, the posterior one whose \fIport\fP list matches the
 111 connecting port.  If the \fB-x\fP \fB--\fP is used, prior \fB-x\fP flags
 112 are ignored.
 113 .P
 114 The \fB-b\fP \fIn\fP \fImaster\fP:\fIport\fP \fIbackup\fP:\fIport\fP flag designates
 115 the backup destination for \fImaster\fP:\fIport\fP.  The program checks
 116 every \fIn\fP seconds whether \fImaster\fP:\fIport\fP is connectable, using
 117 the health check script defined by \fB-s\fP flag described below.
 118 If not, the backup is used instead.  Alternative \fIhost\fP can be
 119 checked, using host=\fIhost\fP and alternative \fIport\fP, using
 120 port=\fIport\fP.
 121 .P
 122 The \fB-s\fP \fIsend\fP \fIexpect\fP... \fB--\fP flag defines the health check
 123 script.  Sending \fIsend\fP, then checks whether the response match
 124 the regular expression \fIexpect\fP.
 125 .P
 126 The \fB-B\fP \fIhost\fP:\fIport\fP \fIhost1\fP:\fIport1\fP... \fB--\fP is for the
 127 destination group.  If the destination of \fIst\fP is \fIhost\fP:\fIport\fP,
 128 the program chooses a destination randomly from the group.  The
 129 destination \fIhost\fP:\fIport\fP that is designated by \fB-b\fP flag and
 130 turned out unhealthy, is excluded from the group.
 131 .P
 132 The \fB-I\fP \fIhost\fP designates the interface used as the source
 133 address of the connection to the desctination.
 134 .P
 135 If the \fB-o\fP \fIn\fP or \fB-g\fP \fIn\fP flag is used, the program set
 136 its uid or gid to \fIn\fP respectively.  If the \fB-t\fP \fIdir\fP
 137 flag (\fIdir\fP is a directory) is used, the program change its
 138 root to the directory.  If the \fB-D\fP flag is used, \fBstone\fP runs
 139 as a daemon. The \fB-c\fP \fIdir\fP flag designates the
 140 directory for core dump.
 141 .P
 142 The \fB-M\fP install \fIname\fP and the \fB-M\fP remove \fIname\fP flags are
 143 for NT service.  \fIname\fP is the service name.  Start the
 144 service using the command: net start \fIname\fP.  To install \fBstone\fP
 145 service as the name \fIrepeater\fP, for example:
 146 .P
 147 .RS
 148 C:\\>\fBstone -M install \fIrepeater\fB -C \fIC:\\stone.cfg\fR
 149 .br
 150 C:\\>\fBnet start \fIrepeater\fR
 151 .RE
 152 .P
 153 The \fB-q\fP \FISSL\FP and the \fB-z\fP \FISSL\FP flags are for SSL
 154 encryption.  The \fB-q\fP \FISSL\FP is for the client mode, that is,
 155 when \fBstone\fP connects to the other SSL server as a SSL client.
 156 The \fB-z\fP \FISSL\FP if for the server mode, that is, when other SSL
 157 clients connect to the \fBstone\fP.
 158 .P
 159 \FISSL\FP is one of the following.
 160 .P
 161 .PD 0
 162 .IP default 15
 163 reset SSL options to the default.
 164 Using multiple \fIst\fP, different SSL options can
 165 be designated for each \fIst\fP.
 166 .IP verbose
 167 verbose mode.
 168 .IP verify
 169 require SSL certificate to the peer.
 170 .IP verify,once
 171 request a client certificate on the initial TLS/SSL
 172 handshake. (\fB-z\fP only)
 173 .IP verify,ifany
 174 The certificate returned (if any) is checked. (\fB-z\fP only)
 175 .IP verify,none
 176 never request SSL certificate to the peer.
 177 .IP crl_check
 178 lookup CRLs.
 179 .IP crl_check_all
 180 lookup CRLs for whole chain.
 181 .IP uniq
 182 if the serial number of peer's SSL certificate
 183 is different from the previous session, deny it.
 184 .IP re\fIn\fP=\fIregex\fP
 185 The certificate of the peer must satisfy the
 186 \fIregex\fP.  \fIn\fP is the depth.  re0 means the subject
 187 of the certificate, and re1 means the issure.
 188 The maximum of \fIn\fP is 9.
 189 if \fIn\fP is negative, re-1 means the root CA and
 190 re-2 means its child CA.
 191 .IP depth=\fIn\fP
 192 The maximum of the certificate chain.
 193 If the peer's certificate exceeds \fIn\fP, the
 194 verification fails.  The maximum of \fIn\fP is 9.
 195 .IP tls1
 196 Just use TLSv1 protocol.
 197 .IP ssl3
 198 Just use SSLv3 protocol.
 199 .IP ssl2
 200 Just use SSLv2 protocol.
 201 .IP no_tls1
 202 Turn off TLSv1 protocol.
 203 .IP no_ssl3
 204 Turn off SSLv3 protocol.
 205 .IP no_ssl2
 206 Turn off SSLv2 protocol.
 207 .IP sni
 208 Server Name Indication (SNI).
 209 .IP servername=\fIstr\fP
 210 The name of the server indicated by SNI.
 211 .IP bugs
 212 Switch on all SSL implementation bug workarounds.
 213 .IP serverpref
 214 Use server's cipher preferences (only SSLv2).
 215 .IP sid_ctx=\fIstr\fP
 216 Set session ID context.
 217 .IP passfile=\fIfile\fP
 218 The filename of the file containing password of the key.
 219 .IP passfilepat=\fIfile\fP
 220 The pattern of the filename.
 221 .IP key=\fIfile\fP
 222 The filename of the secret key of the certificate.
 223 .IP keypat=\fIfile\fP
 224 The pattern of the filename.
 225 .IP cert=\fIfile\fP
 226 The filename of the certificate.
 227 .IP certpat=\fIfile\fP
 228 The pattern of the filename.
 229 .IP certkey=\fIfile\fP
 230 The filename of the certificate with the secret key.
 231 .IP certkeypat=\fIfile\fP
 232 The pattern of the filename.
 233 .IP CAfile=\fIfile\fP
 234 The filename of the certificate of the CA.
 235 .IP CApath=\fIdir\fP
 236 The directory of the certificate files.
 237 .IP pfx=\fIfile\fP
 238 The filename of the PKCS#12 bag.
 239 .IP pfxpat=\fIfile\fP
 240 The pattern of the filename.
 241 .IP store=\fIprop\fP
 242 [Windows] Use the secret key in the Cert Store.
 243 designate by "SUBJ:<substr>" or "THUMB:<hex>".
 244 .IP storeCA
 245 [Windows] Use CA certificates in the Cert Store.
 246 .IP cipher=\fIlist\fP
 247 The list of ciphers.
 248 .IP lb\fIn\fP=\fIm\fP
 249 change the destination according to the
 250 certificate of the peer.  The number calculated
 251 from the matched string to the \fIn\fPth ( ... ) in
 252 the ``regex'' of SSL options (mod \fIm\fP) is used
 253 to select the destination from the destination
 254 group defined by \fB-B\fP flag.
 255 .PD
 256 .P
 257 \fIst\fP is one of the following.  Multiple \fIst\fP can be
 258 designated, separated by \fB--\fP.
 259 .P
 260 .PD 0
 261 .IP (1)
 262 \fIhost\fP:\fIport\fP \fIsport\fP [\fIxhost\fP...]
 263 .IP (2)
 264 \fIhost\fP:\fIport\fP \fIshost\fP:\fIsport\fP [\fIxhost\fP...]
 265 .IP (3)
 266 proxy \fIsport\fP [\fIxhost\fP...]
 267 .IP (4)
 268 \fIhost\fP:\fIport\fP/http \fIsport\fP \fIrequest\fP [\fIxhost\fP...]
 269 .IP (5)
 270 \fIhost\fP:\fIport\fP/proxy \fIsport\fP \fIheader\fP [\fIxhost\fP...]
 271 .IP (6)
 272 health \fIsport\fP [\fIxhost\fP...]
 273 .PD
 274 .P
 275 The program repeats the connection on port \fIsport\fP to the
 276 other machine \fIhost\fP port \fIport\fP.  If the machine, on
 277 which the program runs, has two or more interfaces, type (2) can
 278 be used to repeat the connection on the specified interface
 279 \fIshost\fP.  You can also specify path name that begins with
 280 ``/'' or ``./'', instead of \fIhost\fP:\fIport\fP so that the
 281 program handles a unix domain socket.
 282 .P
 283 Type (3) is a http proxy.  Specify the machine, on which the
 284 program runs, and port \fIsport\fP in the http proxy settings of
 285 your WWW browser.
 286 Extentions can be added to the ``proxy'' like \fIxhost\fP/\fIext\fP.
 287 \fIext\fP is:
 288 .P
 289 .IP v4only
 290 limit the destination within IP addresses.
 291 .IP v6only
 292 limit the destination within IPv6 addresses.
 293 .P
 294 Type (4) relays stream over http request.  \fIrequest\fP is the
 295 request specified in HTTP 1.0.  In the \fIrequest\fP, \ is
 296 the escape character, and the following substitution occurs.
 297 .PP
 298 .RS 8
 299 .PD 0
 300 .IP \\\\n 8
 301 newline  (0x0A)
 302 .IP \\\\r
 303 return   (0x0D)
 304 .IP \\\\t
 305 tab      (0x09)
 306 .IP \\\\\\\\
 307 \ itself (0x5C)
 308 .IP \\\\a
 309 the IP address of the client connecting to the \fBstone\fP.
 310 .IP \\\\A
 311 \fIIP address of the client\fP:\fIport number\fP
 312 .IP \\\\d
 313 the destination IP address
 314 .IP \\\\D
 315 \fIdst IP address\fP:\fIport number\fP (for transparent proxy)
 316 .IP \\\\u
 317 uid (number) of the client
 318 .IP \\\\U
 319 user name of the client
 320 .IP \\\\g
 321 gid (number) of the client
 322 .IP \\\\G
 323 group name of the client
 324 .br
 325 \\u \\U \\g \\G are valid in the case of unix domain socket
 326 .IP \\\\0
 327 the serial number of peer's SSL certificate.
 328 .IP "\\\\1 - \\\\9"
 329 the matched string in the ``regex'' of SSL options.
 330 .IP \\\\?1\fIthen\fP\\\\:\fIelse\fP\\\\/
 331 if \1 (\2 - \9 in a similar way) is not null,
 332 \fIthen\fP, otherwise \fIelse\fP.
 333 .PD
 334 .RE
 335 .P
 336 Type (5) repeats http request with \fIheader\fP in the top of
 337 request headers.  The above escapes can be also used.
 338 If \fI/mproxy\fP is designated instead of \fI/proxy\fP, \fIheader\fP is
 339 added to each request headers.
 340 .P
 341 Type (6) designates the port that other programs can check
 342 whether the \fBstone\fP runs `healthy' or not.  Following commands are
 343 available to check the \fBstone\fP.
 344 .P
 345 .RS 8
 346 .PD 0
 347 .IP "HELO \fIany string\fP" 24
 348 returns the status of the \fBstone\fP
 349 .IP "STAT"
 350 # of threads, mutex conflicts
 351 .IP "FREE"
 352 length of free lists
 353 .IP "CLOCK"
 354 seconds passed
 355 .IP "CVS_ID"
 356 CVS ID
 357 .IP "CONFIG"
 358 content of the configuration file
 359 .IP "STONE"
 360 configuration of each stones
 361 .IP "LIMIT \fIvar\fP \fIn\fP"
 362 check the value of \fIvar\fP is
 363 less than \fIn\fP
 364 .PD
 365 .RE
 366 .P
 367 \fIvar\fP is one of the following:
 368 .P
 369 .RS 8
 370 .PD 0
 371 .IP PAIR 16
 372 the number of ``pair''
 373 .IP CONN
 374 the number of ``conn''
 375 .IP ESTABLISHED
 376 seconds passed since the last conn established
 377 .IP READWRITE
 378 seconds passed since the last read/write
 379 .IP ASYNC
 380 the number of threads
 381 .PD
 382 .RE
 383 .P
 384 The response of the \fBstone\fP is 2xx when normal, or 5xx when
 385 abnormal on the top of line.
 386 .P
 387 If the \fIxhost\fP are used, only machines or its IP addresses
 388 listed in \fIxhost\fP separated by space character can
 389 connect to the program and to be repeated.
 390 .P
 391 Extentions can be added to the \fIxhost\fP like
 392 \fIxhost\fP/\fIex\fP,\fIex\fP....  \fIex\fP is:
 393 .IP \fIm\fP
 394 You can designate the length of prefix bits of the
 395 netmask, so that only machines on specified.  In the
 396 case of class C network 192.168.1.0, for example, use
 397 ``192.168.1.0/24''.
 398 .IP v4
 399 \fIxhost\fP is resolved as the IP address.
 400 .IP v6
 401 \fIxhost\fP is resolved as the IPv6 address.
 402 .IP p\fIm\fP
 403 the data repeated by the program are dumped, only if it
 404 was connected by the machines specified by \fIxhost\fP.  \fIm\fP
 405 is the dump mode, equivalent to the number of \fB-p\fP
 406 options.
 407 .P
 408 Use ``!'' instead of ``\fIxhost\fP'', to deny machines by following
 409 \fIxhost\fP.
 410 .P
 411 Extentions can be added to the \fIport\fP like
 412 \fIport\fP/\fIext\fP,\fIext\fP....  \fIext\fP is:
 413 .IP udp
 414 repeats UDP instead of TCP.
 415 .IP ssl
 416 forwards with encryption.
 417 .IP v6
 418 connects to the destination using IPv6.
 419 .IP base
 420 forwards with MIME base64 encoding.
 421 .P
 422 Extentions can be added to the \fIsport\fP like
 423 \fIsport\fP/\fIext\fP,\fIext\fP....  \fIext\fP is:
 424 .IP udp
 425 repeats UDP instead of TCP.
 426 .IP apop
 427 converts POP to APOP.  The conversion is derived from
 428 the RSA Data Security, Inc. MD5 Message-Digest Algorithm.
 429 .IP ssl
 430 forwards with decryption.
 431 .IP v6
 432 accepts connection using IPv6.  If \fIshost\fP is omitted
 433 like (1), IP is also acceptable.
 434 .IP v6only
 435 accepts connection using IPv6 only.  Even if \fIshost\fP is
 436 omitted like (1), IP is not acceptable.
 437 .IP base
 438 forwards with MIME base64 decoding.
 439 .IP http
 440 relays stream over http.
 441 .IP ident
 442 identifies the owner of the incoming connection
 443 on the peer using ident protocol (RFC1413).
 444 .SH EXAMPLES
 445 .PD 0
 446 .IP \fIouter\fP\^:
 447 a machine in the outside of the firewall
 448 .IP \fIinner\fP\^:
 449 a machine in the inside of the firewall
 450 .IP \fIfwall\fP\^:
 451 the firewall on which the \fBstone\fP is executed
 452 .PD
 453 .TP
 454 \fBstone \fIouter\fB:telnet 10023\fR
 455 Repeats the telnet protocol to \fIouter\fP.
 456 .br
 457 Run telnet fwall 10023 on \fIinner\fR.
 458 .TP
 459 \fBstone \fIouter\fB:domain/udp domain/udp\fR
 460 Repeats the DNS query to \fIouter\fP.
 461 .br
 462 Run \fBnslookup -\fP \fIfwall\fP on \fIinner\fP.
 463 .TP
 464 \fBstone \fIouter\fB:ntp/udp ntp/udp\fR
 465 Repeats the NTP to \fIouter\fP.
 466 .br
 467 Run \fBntpdate \fIfwall\fR on \fIinner\fP.
 468 .TP
 469 \fBstone localhost:http 443/ssl\fR
 470 Make WWW server that supports https.
 471 .br
 472 Access \fBhttps://\fIfwall\fB/\fR using a WWW browser.
 473 .TP
 474 \fBstone localhost:telnet 10023/ssl\fR
 475 Make telnet server that supports SSL.
 476 .br
 477 Run \fBSSLtelnet -z ssl \fIfwall\fB 10023\fR on \fIinner\fP.
 478 .TP
 479 \fBstone proxy 8080\fR
 480 http proxy
 481 .TP
 482 \fBstone\fP \fIouter\fB:110/apop 110\fR
 483 connect to \fIinner\fP:pop using a mailer that does not
 484 support APOP.
 485 .PP
 486 Where \fIfwall\fP is a http proxy (port 8080):
 487 .TP
 488 \fBstone \fIfwall\fB:8080/http 10023 'POST http://\fIouter\fB:8023 HTTP/1.0'\fR
 489 .br
 490 .ns
 491 .TP
 492 \fBstone localhost:telnet 8023/http
 493 .nf
 494 Run \fBstone\fPs on \fIinner\fP and \fIouter\fP respectively.
 495 Relays stream over http.
 496 .TP
 497 \fBstone \fIfwall\fB:8080/proxy 9080 \'Proxy-Authorization: Basic \fIc2VuZ29rdTpoaXJvYWtp\fB\'\fR
 498 for browser that does not support proxy authorization.
 499 .fi
 500 .
 501 .SH HOMEPAGE
 502 The official homepage of \fBstone\fP is:
 503 .br
 504 \fIhttp://www.gcd.org/sengoku/stone/\fP
 505 .
 506 .SH COPYRIGHT
 507 All rights about this program \fBstone\fP are reserved by the
 508 original author, Hiroaki Sengoku.  The program is free software;
 509 you can redistribute it and/or modify it under the terms of the
 510 \fIGNU General Public License (GPL)\fP.  Furthermore you can link it
 511 with openssl.
 512 .
 513 .SH NO WARRANTY
 514 This program is distributed in the hope that it will be useful,
 515 but WITHOUT ANY WARRANTY.
 516 .
 517 .SH AUTHOR
 518 .nf
 519 Hiroaki Sengoku
 520 sengoku@gcd.org
 521 http://www.gcd.org/sengoku/
 522 .fi