.TH socks5.conf 5 "02 May 1997".SH NAMEsocks5.conf \- Configuration file for the socks5 daemon.SH SYNOPSISThe socks5 daemon usually reads the configuration file in /etc/socks5.conf. When you configure and build socks5 with the.PP.RS 5--with-srvconffile=\fIfilename\fP.RE.PPoption, you can change the directory. Under FreeBSD's UNIX port, the configuration file resides in /usr/local/etc/socks5.conf..SH DESCRIPTIONThe socks5 daemon reads the configuration file when it starts and each time it receives an HUP signal. The configuration file contains the information the server needs to determine:.RS 5- the interface to use to reach an address.br - when the server should connect directly to an address.br- when the server should use another proxy server.br- the necessary requirements to make a proxy connection.RE.PPThe configuration file contains six sections:.RS 5- ban host .br- authentication.br - interfaces.br- variables and flags.br- proxies.br- access control.RE.PPIn each section, the socks5 daemon sequentially reads each line until it encounters a matching line for that section. The order of sections and the order of lines within a section are crucial to achieving the desired result. Every entry in a line must match..SH BAN HOST ENTRIESBan host entries identify hosts from which the socks5 daemon should not accept connections and use the syntax:.PP.RS 5ban \fIsource-host source-port\fP.RE.TP 15.B banIndicates not to attempt authentication.TP.B \fIsource-host\fPMust be a valid \fIhostpattern\fP.TP\fIsource-port\fPMust be a valid \fIportpattern\fP.PPThe socks5 daemon refuses connections originating from clients on \fIsource-port\fP at \fIsource-host\fP..SH AUTHENTICATION ENTRIESAuthentication entries identify the types of authentication the socks5 daemon can use. Authentication lines use the syntax:.PP.RS 5auth \fIsource-host source-port auth-methods\fP.RE.TP 15.B authIdentifies the entry as an authentication entry.TP.B \fIsource-host\fPMust be a valid \fIhostpattern\fP.TP\fIsource-port\fPMust be a valid \fIportpattern\fP.TP .B \fIauth-methods\fPMust be a valid \fIauthpattern\fP.PPThe socks5 daemon authenicates clients that originate on \fIsource-port\fP at \fIsource-host\fP using \fIauth-methods\fP..PPWhen the configuration file does not contain \fB auth\fP lines, any authentication works. Omitting auth lines is the same as specifying an \fIauthpattern\fP containing -, any authentication.  If \fBauth\fP lines are used, clients not matching will be refused..PPWhen the socks5 daemon does not require authentication, it receives no user information unless socks5 configuration requires ident responses. Use the SOCKS5_DEMAND_IDENT environment variable to require ident responses. See socks5(1) for a complete description of socks5 environment variables.To ensure that the socks5 daemon receives usernames from the client, and to allow socks4 clients to use the server, set the \fIauthpattern\fP order to n,u. With socks5 clients, the socks daemon chooses Username/Password authentication before no authentication..PPThe socks5 daemon checks \fIauth-methods\fP in reverse order, beginning with the last \fIauth-method\fP in \fIauthpattern\fP. .PP.SH INTERFACE ENTRIESOn machines with multiple interfaces, and therefore multiple IP addresses, frequently administrators want to ensure that socks5 uses certain interfaces with certain addresses. This prevents outside machines from impersonating inside machines by requiring inside machines to use the inside interface and outside machines to use the outside interface. It also allows socks5 to determine on which interface to bind when accepting a bind request, or when issuing a sendto request. .PPWhen socks5 fails to find a match in the configuration file, it uses INADDR_ANY to bind, and receives a connection on any interface. .PPSingle-homed hosts do not require interface entries. Only machines with more than one interface should use interface entries..PP Use this format for interface entries in the socks5.conf file:.RS 5.TP interface \fIhostpattern portpattern interface-address\fP.RE.TP 18.B interfaceIdentifies interface entries.TP\fIhostpattern\fPContains a source or destination host for a connection.TP\fIportpattern\fPContains a source or destination port for a connectionpattern\fP.TP.B \fIinterface-address\fPIdentifies the IP address of an interface card or the name of the interface, for example le0..PPWhen \fIhostpattern\fP or \fIportpattern\fP specify a source address, the patterns define the \fIinterface-address\fP clients must use to connect to the socks5 server when connecting from the host defined in \fIhostpattern\fP or the port defined in \fIportpattern\fP. Connection attempts from interface addresses other than \fIinterface-address\fP fail.When \fIhostpattern\fP or \fIportpattern\fP specify a destination address, the patterns define the interface address the socks5 daemon uses to connect to the host defined in \fIhostpattern\fP or the port defined in \fIportpattern\fP.The \fIinterface\fP entry replaces the \fIroute\fP entry of previous releases.  For the current release, the entries are equivalent.  In future releases, support for \fIroute\fP entries may be removed. .pp.PP.SH VARIABLE ENTRIESVariables and flags in the configuration file control the amount and types of logging and information messages. The configuration file syntax for initializing variables is:.RS 5.TPset \fIvariable\fP \fIvalue\fP.RE.PP.TP 10setIdentifies entries that initialize environment variables for internal use..PRefer to the socks5(1) ENVIRONMENT section for complete details about socks5 environment variables and values..PP.SH PROXY ENTRIESProxy entries describe the addresses clients can only reach through other SOCKS servers and identify how the daemon contacts the host. The daemon contacts the host directly when the configuration file does not contain an entry for that host..RS 5.PP.I proxy-type dest-host dest-port proxy-list.RE.PP.TP 15\fIproxy-type\fPSpecifies the type of proxy server. Valid entries include: .RS 20.TP 10socks5SOCKSv5.TPsocks4SOCKS version 4.TPnoproxyMake direct connection.RE.TP 15.B \fIdest-host\fPMust be a valid \fIhostpattern\fP.TP.B \fIdest-port\fPMust be a valid \fIportpattern\fP.TP.B \fIproxy-list\fPMust be a valid \fIproxypattern\fP and identifies the proxy server(s) to use. .PPThe daemon uses the servers in \fIproxy-list\fP to connect to \fIdest-port\fP on \fIdest-host\fP. The servers is \fIproxy-list\fP must be the same type servers as \fIproxy-type\fP..PP.SH ACCESS CONTROL ENTRIESThe access control section determines when the server permits or denies a request to establish a connection. The socks5 daemon denies a request if an access control line does not match the request, even after it has authenticated the host. .PPThere are two types of lines, permit lines and deny lines, with this syntax:.PP.RS 5permit \fIauth cmd src-host dest-host\fP \\.RE.RS 8\fIsrc-port dest-port [user-list]\fP.RE.PP.RS 5deny \fIauth cmd src-host dest-host\fP \\.RE.RS 8\fI src-port dest-port [user-list]\fP.RE.PP.TP 12.B \fIauth\fPMust be a valid \fIauthpattern\fP and specifies a list of authentication methods..TP.B \fIcmd\fPMust be a valid \fIcommandpattern\fP and specifies the commands clients on \fIsrc-host\fP can execute on \fIdest-host\fP..TP.B \fIsrc-host\fPMust be a valid \fIhostpattern\fP.TP.B \fIdest-host\fPMust be a valid \fIhostpattern\fP.TP.B \fIsrc-port\fPMust be a valid \fIportpattern\fP.TP.B \fIdest-port\fPMust be a valid \fIportpattern\fP .TP .B \fIuser-list\fPMust be a valid \fIuserpattern\fP..PPThe entire line matches only when all the entries match..PP.SH PATTERNS.SH \fIhostpattern\fPsocks5 requires host addresses and netmasks to determine the hosts that apply to a socks5.conf entry. Specify the host/mask pair as a \fIhostpattern\fP, using the format: .TP 15.B hostip/maskMatches when a host address bitwise anded with the mask equals the hostip anded with the mask. Use the hostip/mask to mask the host portion of the address from the network or subnetwork portion..TP.B -all hosts match.TP.B n1.equivalent to n1.0.0.0/255.0.0.0.TP.B n1.n2.equivalent to n1.n2.0.0/255.255.0.0.TP.B n1.n2.n3.equivalent to n1.n2.n3.0/255.255.255.0.TP.B .domain.namehostname must end with .domain.name.TP.B a.host.namehostname must match exactly with a.host.name..PPIf domain names are used, SOCKS5_REVERSEMAP must be set.  Because hostnames and domains depend on DNS, using IP addresses and netmasks is recommended.  In many cases, reverse DNS maps are not implemented or incorrect..PPAlthough socks5.conf supports older \fIhostpattern\fP syntax, we recommend using the newer method. The newer method is also easier to read. The older \fIhostpattern\fP syntax is:.RS 5.TP 15.B hostip/aall hosts match, same as "-".TP.B hostip/nnetwork match. Masks the host and subnet portions of the address, leaving the network portion. The IP address class for hostip determines the mask..TP.B hostip/ssubnet match. Masks the host portion of the address, leaving the subnetwork and network portion. The IP address class for hostip determines the mask..TP.B hostip/hhost match, the same as hostip.RE.PP.SH \fIportpattern\fPSpecify ports in a \fIportpattern\fP as a service name, number, or range. Enclose ranges in brackets to indicate the range is inclusive, or parentheses to indicate the range is non-inclusive. Specify the range as two port names or numbers, separated by a comma, with no white space..RS 5.TP 15.B tftpthe service port for tftp, usually port 69.TP.B 80port 80.TP.B -all ports.TP.B [100,1000]ports 100 through 1000.TP.B (100,1000)ports 101 through 999.TP.B (100,1000]ports 101 through 1000.RE.PP.SH \fIauthpattern\fPSpecify authentication methods in an \fIauthpattern\fP as a comma separated list of letters, with no white space. The socks5 daemon checks \fI auth-methods\fP in reverse order, beginning with the last \fIauth-method\fP in \fI authpattern\fP. socks5.conf recognizes these authentication methods:.RS 5.TP.B nNo authentication. If you built the socks5 daemon with ident, the server authenticates UNIX users..TP.B uUsername/Password.TP.B kKerberos 5 (GSS-API).TP.B -any authentication method .RE.PPThe last \fIauth-method\fP listed takes precedence over the methods listed first. For example, if you list:.RS 5.PPn,u,k .PP.REthe server requests Kerberos authentication for socks5 clients. If the socks5 client is not set up to use Kerberos, the server uses Username/Password authentication. .PPSince SOCKS4 clients can not use Kerberos or Username/Password authentication, the server does not require authentication for SOCKS4 clients. .PPIf you list:.RS 5.PPn,k,u.PP.REthe server requests Username/Password authentication for socks5 clients. Since SOCKS4 clients can not use Username/Password or Kerberos authentication, the server does not require authentication for SOCKS4 clients. .PP.SH \fIcommandpattern\fPSpecify commands in a \fIcommandpattern\fP as a comma separated list of letters, with no white space. socks5.conf recognizes these commands:.RS 5.TP.B cconnect.TP.B bbind.TP.B uUDP.TP.B pping.TP.B ttraceroute.TP.B -all commands.RE.PP.SH \fIuserpattern\fPSpecify multiple users in a \fIuserpattern\fP as a comma separated list of individual users, with no white space and no wild card patterns..PPThe user type must match the authentication method. For example, when you specify Username/Password authentication, the socks5 daemon expects socks5 users. When you specify Kerberos authentication, the socks5 daemon expects Kerberos users. A dash, -, matches all users.When you specify u and k in the \fIauthpattern\fP, \fIuserpattern\fP can contain valid Kerberos and socks5 users..PP.SH \fIproxypattern\fPSpecify socks5 daemons in a \fIproxypattern\fP as a comma separated list of \fIserver-entries\fP, with no white space. .PPSpecify servers in order of preference. The client attempts to connect to servers in the order in which they are listed in the \fIproxypattern\fP. It only attempts connections to a server when the preceeding server is not available. .PP.SH \fIserver-entries\fPA server entry is a hostname or IP address, optionally followed by a colon and the port number, with no white space. When you omit the port number, socks5 uses the default port..RS 5.TP 15.B hosthostname, default port.TP.B host:porthostname, specified port.PP.RE.PP.SH EXAMPLESRefer to the examples directory for more complete examples..PP.RS 5auth - - k.brpermit k - 111.111.111. - - -.RE.PPOnly kerberos authenticated users from the class C network 111.111.111.0 can use the server..PP.RS 5socks5 - - s5srv1,s5srv2.brpermit - - .mydomain.com - - -.RE.PPAll socks5 requests connect through s5srv1. If s5srv1 is not available, all socks5 requests connect through s5srv2.  Only clients from .mydomain.com can use the server..PP.RS 5auth otherserver - k.brnoproxy .internal.net.com -.brsocks5 - - otherserver.brpermit - - .internal.net.com - - -.brpermit k - otherserver - - -.br.RE.PPClients from .internal.net.com can use the server without kerberos authentication.The socks5 server will connect directly to .internal.net.com hosts and proxy throughanother socks5 server, otherserver, for other hosts.  For the other socks5 server,otherserver, to proxy through this socks5 server, it must authenticate with kerberos..PP.SH POOR CONFIGURATIONSAs with any software that has security issues, proper configuration is a \fBmust\fP.  The line.PPpermit - - - - - -.PPshould never be used.  With this configuration, malicious users could use the socks5server to hide their attack of other systems.  Always try to restrict based on sourceor destination host..PP.SH SEE ALSOsocks5(1), libsocks5.conf(5), sockd4_to_5.pl(1).PP.SH AUTHORSNWSL SOCKS5 Development Team.PPSend comments to socks5-comments@socks.nec.com