Orenosp User's Guide for version 1.1.0 or later Table of Contents - HTTP/HTTPS Reverse Proxy Basics - Examples - Absolute URLs in Contents - Load-Balancing HTTP/HTTPS Servers - Enabling Various SSL-related Features - Virtual hosts and SSL server certificate - HTTP Compression - Various Built-in Security Filters - Nimda Filters - Referer Checking - Request Policing - Access and Performance Logging - User Authentication - Passing Through Authentication to Backend - Authenticating and Authorizing at Reverse Proxy - HTTP Basic Authentication - Form Based Authentication - SSL Client Certificate Authentication - External Authentication Services - HTTP/HTTPS Basic Auth Server - File-based authentication - PAM authentication - LDAP authentication - RADIUS authentication - Client Certificate Mapping and Authorization - Steps - Certificate Mapping Rules - IP-based Access Control - Monitoring Module - Bandwidth Control - Local File Serving for Menu Pages - Processing Order - IPv4 <-> IPv6 - Proxy-Backend Communication - Adding Arbitrary Request/Response Headers - Simple Content Rewrite - Regular Expression Based Content Rewrite - Response Headers Rewrite - Cookie Attribute Translation - Advanced Reverse Proxy Configurations - Outlook Web Access (OWA) - Quick Configurations - Basics - OWA's use of WebDAV - Alternative Reverse Proxy Configuration - User Authentication and Authorization - Implementing Idle Session Timeout - About Logging Out - Multiple OWA Servers - Windows SharePoint Services (WSS) - Interoperability Tips with IIS - Miscellaneous Parameters - SSL Client Authentication - SSL Profiles - Appendice - Setting Up a Simple Windows RAIDUS Server (IAS) For Secure Port Forwarding (SSL Tunneling), see SSL Tunneling Guide (tunnel/ssltunnel_en.txt). [Some sections are not yet translated to English] HTTP/HTTPS Reverse Proxy Basics =============================== Examples -------- [Example-1 and 2 are skipped for now] See "Advanced Reverse Proxy Configurations" section for more complex examples. Example-3 Publish internal servers via multiple virtual hostnames. The internal servers are really virtual servers hosted on localhost. external port/hostname internal vhostname web page (Orenosp) (internal http server) ---------------------------------------------------------------------------- 443 https : spub1.example.com --> secure-pub-1 http secure public web page 1 443 https : spub2.example.com --> secure-pub-2 http secure pulibc web page 2 443 https : sadmin.example.com --> secure-admin http admin web page --- sproxy.conf --- # define only one listen port # proxy_listen_name = lis-ssl 0.0.0.0@443 https # The backend server to forward the request to is determined by Host: # header in the original request. When forwarding it to the backend, # send vhostname specified with -hh option as Host: header. # #

proxy_pass_by = vhost spub1.example.com http://localhost -hh=unsecure-pub proxy_pass_by = vhost spub2.example.com http://localhost -hh=secure-pub proxy_pass_by = vhost sadmin.example.com http://localhost -hh=secure-admin --- internal web server configuration --- - listen on port 80 - publish secure public web page 1 via vhostname secure-pub-1 - publish secure public web page 2 via vhostname secure-pub-2 - publish admin web page 1 via vhostname secure-admin - in all vhosts, restrict access to those from Orenosp using IP address restriction. --- notes when using this method for HTTPS --- see "Virtual hosts and SSL server certificate" section. Example-4 Publish, via a single hostname, multiple applications scattered over multiple servers. App1 and App2 exist under /app1/ on appserver1 and /app2/ on appserver2 respectively. https://appserver1/app1/ Application-1 http://appserver2/app2/ Application-2 We want to publish these apps via a single external proxy of https://mine.example.com/. https://mine.example.com/app1/ --> https://appserver1/app1/ https://mine.example.com/app2/ --> http://appserver2/app2/ --- sproxy.conf --- # define only one listen port # proxy_listen_name = lis-ssl 0.0.0.0@443 https # forward all requests received at lis-ssl and having paths of /app1/* # to https://appserver1/app1/. # forward all requests received at lis-ssl and having paths of /app2/* # to http://appserver2/app2/. # all other requests are denied as errors. #

proxy_pass_by = url lis-ssl://*/app1/ https://appserver1/app1/ proxy_pass_by = url lis-ssl://*/app2/ http://appserver2/app2/ --- internal web server configurations --- As done in the example, if you can use the same path for external url and internal url, there is not much application or configuration changes. However, if you can't use the same path, either application must be changed to use relative paths or you must use Orenosp's content rewrite to rewrite paths in HTML pages. Some applications cannot be published in this way due to their content. Example-5 Sending a fixed authentication info to backend server that requires HTTP basic authentication. Orenosp allows client and backend to transparently exchange any authentication information. You can also configure the proxy to send a fixed basic auth credential to a backend server. proxy_pass_by = lis lis-ssl http://username:password@localhost:10001 See also "Advanced Reverse Proxy Configurations" section for more complex examples. Absolute URLs in Contents ------------------------- Generally if a web application is put behind a reverse proxy, its contents shouldn't have absolute URLs in them. But if you already have such an application, then there are two options: 1) Contents that use $SERVER_NAME and friends to achieve site-name independence -> specify -hh="_self_" 2) Contents that have literal absolute URLs -> specify -rw_url=on (automatic URL rewriting in content) e.g., proxy_pass_by = url lis-ssl://*/app1/ \ https://appserver1/app1/ -rw_url=on If you have an application that spans multiple web servers and has pages that link to one another, the automatic URL rewriting (-rw_url) won't solve the problem. In this case, you need to manually configure content rewrite rules. (See Content Rewrite) Load-Balancing HTTP/HTTPS Servers ================================= With load-balancing, you can distribute HTTP request processing among multiple equivalently configured backend servers. In the basic reverse proxy mode, destinations of requests are specified as a regular HTTP or HTTPS URLs. To use multiple servers for load-balancing you will instead need to define a load-balancing group (LB group) and specify the defined LB group as the destination in proxy_pass_by rules. proxy_lbgroup_define = lbhost1 http nodes="server1,server2:8890,server3:8888"

... proxy_pass_by = vhost www.example.com lbgrp://lbhost1 -hh="..." nodes= option specifies a list of servers that will share the request processing load. A node should be specified with its hostname and an optional port number. (Note: do not specify http and https default port numbers, 80 and 443). -hh option in proxy_pass_by, if specified, applies to all the nodes in a group equally. Session Binding --------------- By default, once an HTTP session is assigned to a particular LB node, all requests from that session will go to the same LB node. This is accomplished by using an HTTP cookie ("orenosp-lbg-"). Session binding modes supported: cookie insert mode : the only one supported now other modes that may be supported in future: backend cookie mode : uses backend-supplied cookie client IP range mode : uses client IP address Load-Balancing Algorithm ------------------------ Currently Orenosp does a simple round-robin. High Availability ----------------- Orenosp proactively health-check all nodes in LB groups. In every 5 seconds, it "pings" all nodes using ICMP echo requests. If a node fails to respond to this ping request, it is considered Non-Existent (NOEX). For all other nodes that responded to pings, Orenosp sends a HTTP request: GET http-or-https://node-hostname[:port]/ If the node returns a bad status or fails to respond, it is considered Service-Down (DOWN). Otherwise, the node is considered Service-UP (UP). HTTP status codes that are considered bad are 500 (internal server error), 502 (bad gateway), 503 (service unavailable) and 504 (gateway time out). If the node's state is not UP, it is considered as dead and is temporarily evicted from its LB group. When the node's state becomes UP, it is allowed to join back to the LB group. To rephrase, Orenosp does two periodic checks: (1) Ping check : all nodes (2) HTTP check : all non-NOEX nodes (DOWN and UP nodes) Apart from the peridic checks, Orenosp also retries to send the client HTTP request to another node if the first request fails. If you want to take a node into maintenance, you can just shutdown its HTTP service, shutdown the OS, or just remove the node from the network. After the maintenance, you can start the HTTP service or plug-in the network again. --- Tunables --- You can configure the HTTP check to be applied only for DOWN nodes. This way, you can avoid periodic HTTP check on UP nodes. You still get a similar level of high availability. proxy_lb_hcheck_downonly = 1 Monitoring ---------- You can configure Orenosp monitoring module and check status of LB groups. See "Monitoring Module" later in this guide. Enabling Various SSL-related Features ===================================== 1) Enabling Basic SSL Proxy Follow "Basic Configuration and SSL certificate Setup" in readme_en.txt 2) Enabling Proxy That Requests Client Certificates Follow "SSL Client Authentication" in this Orenosp Users Guide. 3) Configuring Certificate Based Access Control Follow "Client Certificate Mapping and Authorization" in this Orenosp Users Guide. 4) Passing Certificate Information to Backend Servers See "Passing Client Certificate Information to Backend Servers" subsection of "Proxy-Backend Communication" section in this Orenosp Users Guide. 5) Using Multiple SSL Profiles See "SSL Profiles" section in tihs Orenosp Users Guide. Virtual hosts and SSL server certificate ======================================== Notes when publishing multiple virtual hostnames on a single SSL listen port (IP address + port). A client browser will warn the user if the hostname included in the server certificate does not match with the actual hostname that the user is accessing. In order to avoid this, you need to create a server certificate using either of the following methods. 1) Put multiple vhost names in the server certificate (subjectAltName) vhost1 : myweb1.example.com vhost2 : myweb2.example.com vhost3 : myadmin.example.com subjectAltName in certificate: DNS:myweb1.example.com, DNS:myweb2.example.com, DNS:admin.example.com If using gencert, start "gencert -gen -1" and answer Y to "Do you want to put multitple DNS names?(y/n)", and put the next line: myweb1.example.com, myweb2.example.com, admin.example.com This way, you can have a certificate with multiple hostnames. 2) Put a wildcard hostname in CN of the certificate (wildcard certificate) vhost1 : www.myexample.com vhost2 : www2.myexample.com vhost3 : admin.myexample.com CN in certificate : *.myexample.com HTTP Compression ================ In sproxy.conf, find the following lines and uncomment them. #proxy_filter_define = comp-txtonly mod_filt_zlib mtype="text/" #proxy_filter_assign = * comp-txtonly Configured this way, all respose bodies (content) that statisfies all of the following conditions will be sent in compressed form to the client: - HTTP status is 200 (HTTP_OK) - are text files (their MIME type name begins with "text/") - the client (requester) can accept HTTP compressed response See Also Orenosv's users guide and config files. http://hp.vector.co.jp/authors/VA027031/orenosv/guide_en.txt http://hp.vector.co.jp/authors/VA027031/orenosv/http_dflt.txt Various Built-in Security Filters ================================= Nimda Filters ------------- See sproxy_full.txt Referer Checking ---------------- See sproxy_full.txt Request Policing ---------------- See sproxy_full.txt Access and Performance Logging ============================== - Access Logging See proxy_log_access_XXX parameters in sproxy_full.txt - Performance Logging You can add request's response time access logs by specifying 0004 flag to proxy_log_access_flags. The reponse time is defined as the time in seconds from when the request is received from the client and when the proxy has finished sending the last byte of the content. You can also have another dedicated performance logging for tracking backend response times. proxy_perf_logio = single perf.log Format for performance log files time: time when the front request is received from client hmethod: HTTP verb in backend request url: request URL to backend (enclosed by "") hstatus: HTTP status from backend inbytes: bytes sent to backend (sizeof request body) outbytes: bytes received from backend (size of response body) tm_connect: (2-1) time(msec) to connect tm_sendreq: (3-2) time(msec) to send request including req body tm_waitres: (4-3) time(msec) to wait for response headers tm_recvbody (5-4) time(msec) to receive all response body As of version 0.4.2, inbytes are not yet correctly reflected in the log. Because backend connections are cached, if Orenosp can use a cached connection, tm_connect will be very small in that case. - Remote Logging You can direct Orenosp to send log records to a Logging Service running on another PC. This function is applicable to the following logs: proxy_log_access_io, proxy_perf_logio, proxy_nimda_logio, proxy_htrace_logio Syntax of proxy_log_access_io: proxy_log_access_io = remote hostname:port { ssl | tcp } label hostname:port : log service's hostname and TCP port { ssl | tcp } Specify "ssl" to connect over SSL. SSL profile "cldflt" is used for the SSL operations. Specify "tcp" (or its synonym "raw") to connect over TCP. Note that logging communication including username and password will not be encrypted. label : any string that the log service requires -u=username:password : username and password to connect to the log service example proxy_log_access_io = remote host1:13000 ssl /host1/proxy \ -u=logadmin:passwd [Developing a compatible network log service] Please see remote_log_spec.txt. User Authentication =================== You have two options regarding authentication and authorization of access to internal servers. One is to let all requests through, and let each backend server do its authentication and authorization. The other option is to have the reverse proxy to authenticate and authorize these requests. There are three methods for authenticating and authorizing users on client (front) connections. You can combine any of them. Passing Through Authentication to Backend ----------------------------------------- By default Orenosp will relay HTTP basic, HTTP digest and any types of cookie-based authentication/authorization requests from/to backend servers. Windows Integrated Authentication: By default Orenosp will not pass through Microsoft-proprietary HTTP authentication methods. These include MS NTLM authentication and MS Negotiate authentication. When orenosp finds response headers requesting one of these auth methods, it will silently drops that response header. See proxy_auth_disable_XXX parameters in sproxy_full.txt. Set the following parameter to enable these auth methods. proxy_auth_disable_ntlm = 0 proxy_auth_disable_negotiate = 0 Authenticating and Authorizing at Reverse Proxy ----------------------------------------------- 1) HTTP Basic Authentication This is the most simple and easy method. If your backend server also enforces HTTP Basic Authentication, it won't work because each of the reverse proxy (front-end) and the backnd will request a basic authentication. There are three options: - Use a form based authentication at the proxy. - Specify a fixed username and password in backend specifier in proxy_pass_by parameter. (uname:passwd@backend:8888). - Have the proxy to pass username and password received to the backend. The latter only works if your proxy and backend server uses the same authentication database. (You need to set "proxy_auth_pass_to_backend = 1") 2) Form Based Authentication This is probably the most prefered method by users and server admins. Form Based Authentication provides you with a set of customizable HTML pages for authentication process. Another advantage is that it can coexist with backend's basic or form-based authentication because it uses a cookie named 'orenosp-authck-XXX'. You can also pass username and password received to the backend as an HTTP basic auth information. (You need to set "proxy_authck_pass_to_backend = 1") 3) SSL Client Certificate Authentication See section "Client Certificate Mapping and Authorization". HTTP Basic Authentication ------------------------- #proxy_auth_url =

[options] proxy_auth_url = lis-ssl://*/* -u="user1:pass1" -rlm="Local Server" proxy_auth_url = lis-ssl2://*/* -u="user2:pass2" -rlm="Note Server" # [optional] pass user credential to backend's basic auth proxy_auth_pass_to_backend = 1 Form Based Authentication ------------------------- - make a directory /_formauth - copy all files from /padmin/_formauth to /_formauth. You can do this with a single command in a command prompt: > cd > xcopy padmin\_formauth _formauth\ [Linux/Mac]$ cp -R padmin/_formauth _formauth Edit sproxy.conf - enable Form Based Authentication proxy_authck_enable = 1 - [optional] # pass user credential to backend's basic auth proxy_authck_pass_to_backend = 1 - define authentication type(s) (protection realm) proxy_authck_define = noone -u="" -rlm="nobody allowed" proxy_authck_define = fmauth1 -u="user1:passwd1,user2:passwd2" \ -rlm="Restricted Area" -u specifies list of users and their passwords. You can set empty passwords to direct the proxy to use an external authentication server. e.g., -u="user1:,user2:" (you must put ':' even if no password is specified). see External Authentication Servers for details. -rlm specifies the name of the protection realm. If omitted, the name of the authentication type is used ("fmauth1" in the example). -tmo= : idle login timeout in minutes (must be >= 2) default is 30 (minutes). -ckdomain="domain-name" : specifies "domain" name in the ticket cookie. if you have two vhosts, www.example.com and www2.example.com, you could set -ckdomain=".example.com" (notice the leading dot) so that a user could be authenticated just once for all vhosts in *.example.com. - map virtual paths or URL space to protection realms defined proxy_authck_assign = * fmauth1 or if you only want to protect URL space in vhost1, do: proxy_authck_assign = *://vhost1.example.com/* fmauth1 NOTE: By default, access to any vpath space is unrestricted. If you want access restriction for all possible vpath space, be sure to include the following parameter BEFORE any other "proxy_authck_assign" parameters: # for all others, deny any access proxy_authck_assign = * noone - OPTIONAL: add authorization list The protection domain defined by proxy_authck_define is really a user authentication domain. Additionally, for each URL space, you can specify a list of users who should be allowed access. # anyone who are successfully authenticated can access. proxy_authck_assign = *://vhost1.example.com/* fmauth1 # for /private/* space, only user "admin1" and users in "admin" group # will be allowed access. proxy_authck_assign = *://vhost1.example.com/private/* fmauth1 \ -allow="admin1,@admins" User grouping information is stored in /grpdb.txt. Access protected pages When you access any protected pages, you will be redirected to "/_formauth/login.html". When the proxy redirects you, it also sends a cookie that specifies the protection realm for the access-attemped page. (In the above example, "Restricted Area" is the realm.) The proxy will use this realm name to look up an appropriate authck type with which to authenticate the user. Note that if you acess "/_formauth/login.html" directly without being redirected, the proxy will not have a realm name. In such a case the proxy will default to use the last authck type defined in the config file. This is a change from versrion 0.4.1 or earlier, where authentication would simply fail without a proper realm name cookie. The new behavior is preferable in cases where users tend to bookmark login pages. Customizing form-based authentication pages By enabling the form based authentication, any virtual paths that begin with "/_formauth/": - are intercepted by the proxy - will be accessible without __any form-based authentication__ - any files in $ORENOSP_HOME/_formauth directory are sent by the proxy. Therefore you can embed any files that exist in the same directory in the authenticating pages. The following are the special files accessed by the form-based auth module: /_formauth/validate : virtual path for builtin password validator (not customizable) /_formauth/login.html : login page in HTML /_formauth/loginerror.html : login error page in HTML /_formauth/loginsuccess.html : Success report page in HTML /_formauth/denied.html : access denied error page in HTML You can place other html files, icon files, javascript files, or any other type of files in this directory. Coordinating form-based authentication and IP-based access control You can configure the system so that form-based authentication will control any of the IP-based access control methods in Orenosp. Example o Orenosp listens on port 3339 for relayed TCP connections to a Remote Desktop in the LAN. Initially the tunneling listen port is restricted by IP-based access control so that no machine can connect. o When a client first connects to the HTTPS reverse proxy, the client will authenticate himself with Orenosp's form-based authentication. Then, the tunneling listen port will be "opened" for the IP address of that client. o When 60 minutes pass, the tunneling listen port will be "closed" for the client's IP. - create an empty text file "ipacl_rawrdp.txt" in ORENOSP_HOME directory. - add the following parameters: tunnel_listen_name = rdp-raw 0.0.0.0@3391 raw -ip_allow="@ipacl_rawrdp.txt" \ -ip_order=allow-deny proxy_authck_define = fmusers -u="_valid_:" -rlm="Our Users" -tmo=90 \ -onlogin=ipacl_add:ipacl_rawrdp.txt -onlogin=ipacl_tmo:60 end of example You can use any IP-based access control methods (proxy listen port, proxy_authip_url, or tunneling listen port) External Authentication Services ================================ Both the form-based authentication and HTTP basic authentication support external authentication services to verify user passwords. You can direct these auth modules to call the designated authentication service by putting an empty password in the user-password-list. An empty password can be specifed as "username:" (you have to put ':'). You can also use a special username "_valid_" to allow any user who is successfully authenticated by the backend server. e.g., -u="_valid_:" Currently there are four types of external authentication services supported: - HTTP/HTTPS basic auth server Send HEAD request along with username and password to . If it returns status 200, the user is authenticated. Details of actual behavior: send HEAD request first without user auth info and see if designated server actually requires authentication. If so, then send another HEAD request this time with authentication info and see if the server returns 200 status. Only then the user is authenticated. For all other cases, the user is not authenticated. - File-based authentication Authenticates username and password against "passwd.txt" file which usually resides in . Also, when using this method, you can authenticate users against the OS's native authentication mechanism (os_acl option). See Orenosv Users Guide for detail for this. - PAM authentication (Linux and Mac OS X versions only) Authenticate username and password using a PAM rule specified by "orenosp". You need to create /etc/pam.d/orenosp, possibly by copying another entry like "login" or "system-auth". - LDAP authentication (ActiveDirectory) Authenticate username and password by executing LDAP bind to the LDAP server. Currently, the LDAP server is assumed to be an Active Directory. - RADIUS authentication Authenticate user using username and passwod against a RADIUS server. Currently, PAP and CHAP (not MS-CHAP) are supported as authentication methods. For setting up a simple Windows IAS (RADIUS server), see the one of the appendice in this guide. To specify HTTP server auth service: - Prepare a web server that requires HTTP basic authentication. Say, "https://authserver1". (You can use either http or https web server) - for Form Based Authentication proxy_authck_authsrv_url = https://authserver1/ - for HTTP Basic Authentication proxy_auth_authsrv_url = https://authserver1/ To specify file-based auth service: - for Form Based Authentication proxy_authck_authsrv_file = passwd.txt - for HTTP Basic Authentication proxy_auth_authsrv_file = passwd.txt To specify PAM auth service: - for Form Based Authentication proxy_authck_authsrv_pam = svcname=orenosp - for HTTP Basic Authentication proxy_auth_authsrv_pam = svcname=orenosp To specify LDAP auth service: - for Form Based Authentication proxy_authck_authsrv_ldap = - for HTTP Basic Authentication proxy_auth_authsrv_ldap =

are ldap_server= IP Address or hostname of LDAP server. Note that default TCP port number (389) is used. upn_domain= Active Directory's domain name (e.g., example.com). Client's username and this domain name are concatanated with '@', then used as LDAP authentication username. (user1@example.com) user_dn= An alternative for upn_domain. e.g., user_dn="cn=%s ,cn=Users,dc=example,dc=com" To specify RADIUS auth service: - for Form Based Authentication proxy_authck_authsrv_radius = - for HTTP Basic Authentication proxy_auth_authsrv_radius = are conf= The default is "radius.conf" under . auth={pap|chap} RADIUS auth metho to use. The default is "pap". A sample "radius.conf" file is included as /padmin/doc/radius.conf. Note if there are more than one type of parameters in sproxy.conf, the following order of precedence exists: url -> file -> pam -> ldap -> radius Note when using HTTP basic authentication (proxy_auth_xxx), user's password must be verified on every request to protected pages. In order to reduce authentication queries to auth services, the proxy caches both positive and negative query results in memory. These caches time out in 3 minutes. Client Certificate Mapping and Authorization ============================================ You can use SSL client certificates to authenticate users and enforce access contol based on them. First you enable SSL Client Authentication, then you use Client Certificate Mapping for two purposes. 1) Authorize access based on certain certificate attributes. 2) Establish mappings between certificates and usernames which will be used in subsequent authentication/authorization mechanisms (like basic auth and form-based auth). In 1) usage, you can protect a certain URL space by restricting access to those clients who have certficates with certain attributes. Let's say you want to restrict access to clients having certificates with "O=Tange Kentou Club". Then map all clients with Tange Kentou Club to a single username "tange-club", and restrict access to that user. In 2) usage, you don't really protect URL spaces, but just specify certificate to username mapping rules for URL spaces. You also need to specify other authentication/authorization rules (like basic auth and/or form-based auth), which would require the client to use the mapped username. For example, if a client having a certificate with "CN=Joe Yabuki" is mapped to "jyabuki", then the client will be required to use "jyabuki" as username for subsequent basic auth and/or form-based auth. Parameters used (see sproxy_full.txt for complete list of options): proxy_authcert_define = ... proxy_authcert_assign =

Steps - Enable SSL Client Authentication by following "SSL Client Authentication" section. You need to set proxy_ssl_clauth to either "require" or "optional". proxy_ssl_clauth = require or proxy_ssl_clauth = optional If you choose "require" your users will need to present a valid certificate upon connecting your proxy. If they don't, an HTTPS connection will not be established. If you choose "optional" your users will not be required to present a valid certificate but offered a chance to present one upon connecting your proxy. So "optional" allows both users with a certificate and without a certificate to connect. Interoperability Note: Using "optional" will cause very old browsers to stop connecting if the user can't supply a valid certificate. So make sure all browsers you support don't have this kind of problem. - Define certificate mapping and authorization rules A) Restrict access to users with "O=Shiraki Corporation, OU=Boxing Gym" --- certmap.txt --- shiraki-boxing Subject O=Shiraki Corporation, OU=Boxing Gym --- end --- --- sproxy.conf --- # allow certificate-mapped users user1 and user2 proxy_authcert_define = shiraki -u="shiraki-boxing" -cmap=certmap.txt proxy_authcert_assign = * shiraki B) Map certificate to a username and require that username in subsequent basic or form-based authentication / authorization The key option here is "-set_username=1". --- certmap.txt --- jyabuki Subject CN=Joe Yabuki, O=Tange Kentou Club tange Subject CN=Tange, O=Tange Kentou Club --- end --- # establish mapped username to be required in subquent other auths. # That is, Joe needs to log in as "jyabuki" for subsequent form-based auth, # and Tange needs to log in as "tange" for subsequent form-based auth. proxy_authcert_define = tange -u="_valid_" -set_username=1 -cmap=certmap.txt proxy_authcert_assign = * tange # use mapped username in form-based auth proxy_authck_define = ... -u="jyabuki,tange" Certificate Mapping Rules ------------------------- The default filename used for storing certificate mapping rules is /certmap.txt. You can specify a different file with -cmap= option. Modification to the specified file is monitored by Orenosp and the file is re-read as necessary. You don't have to restart Orenosp to reflect changes. Syntax

: username to mapp to

Subject ,,... Hash_SHA1 If you need other matching method, please request to the auther. DN-Pattern : the following attribute names are recognized: CN : Common Name O : Organization Name OU : Organization Unit Name L : Locality Name C : Country Name E : EmailAddress - the following can be used in subject DN matching only (not for issuer DN) NOT YET IMPLEMENTED altDNSName : subject alternative name - DNS name (hostname) altEmail : subject alternative name - Email address If an attribute value contains a ',', it must be prefixed by '\'. O=Shiraki Corporation\, Inc., OU=Boxing Gym certificate-fingerprint-in-SHA1-in-hex : can accept two forms ':'-separated: 57:E7:BB:5D:20:D3:61:49:B9:F1:5E:18:14:6D:43:84:85:75:88:BB ' '-separated: 57 e7 bb 5d 20 d3 61 49 b9 f1 5e 18 14 6d 43 84 85 75 88 bb IP-based Access Control ======================= IP-based Access Control can be enforced in two ways: - per connection basis (specified in proxy_listen_name and tunnel_listen_name) - per request basis (specified by proxy_authip_url) Per-connection access control is more effective because it checks client's IP before establishing an SSL / HTTP connection, thereby thwarting SSL handshake DoS attacks. Per-request access control gives you more flexibility by giving finer control over URL space that a user is allowed to access. Both methods can use either the same access control list or separate ones. That is, you can specify a text-based IP pattern file to both modules. The IP pattern file can be edited while the service is running. Orenosp will detects file modification and reloads patterns from the file. There's no limit on the number of IP patterns in a file. --- a sample IP pattern file --- # you can comment out a line with '#' 123.123.0.0/16 123.234.0.0/16 234.123.123.128 --- end --- Refer to sproxy_full.txt for more details - "ip_allow/ip_deny/ip_order" options in proxy_listen_name - "IP-based Access Authorization" (proxy_authip_url) Monitoring Module ================= The monitoring module can be set up to display list of current connections and other various internal states within the Orenosp process. See Monitoring Module in sproxy_full.txt for list of parameters. Network Mappter --------------- Network Mappter is part of the monitoring module. You can use it to browse PCs within the LAN and possibly wake up a wake-up-enabled PC. See Monitoring Module - Network Map in sproxy_full.txt for list of parameters. Bandwidth Control (Throttling) ============================== See sproxy_full.txt for actual parameters. IMPORTANT : current limitations - Only the SEND direction (reverse proxy sending out contents) is currently supported. - BW control works over data that have not been processed by output filters. This means that the amount of data that's subjected to the bandwidth control will differ from the actual amount of data that goes over the wire. For example, if the HTTP compression filter reduces a 1MB content by 90%, the bandwidth control will see it as 1MB of data even though only the 100KB of data is actually sent over the wire. A work around would be to let the backend server to compress the contents and let them through the reverse proxy. Of course, it won't be possible to rewrite contents with this way. Local File Serving for Menu Pages ================================= If you have multiple servers/services through the proxy, you may want to have a "welcome" menu page. Usually one of the backend servers will host such a page. However, in case you can't place such a page on your backend server for some reason (say all of your http servers are devices), orenosp has a simple local file serving capability. If you set proxy_lfile_enable = 1 then, any files under /_intmenu/ directory will be available to the client with URLs of /_intmenu/XXX. Note that the request for such files are subject to regular authentication and authorization check done by the proxy, namely either by Simple basic auth or Form based auth. You should also set up a redirect from top url ("/") to "/_intmenu/menu.html" to guide users to the menu page. # redirect "/" to /_intmenu/menu.html (note "-s" option) proxy_redirect_by = url lis-ssl://host.com/ https://host.com/_intmenu/menu.html -s Processing Order ================ - [On connect only] Per-Connection IP-based Access Control - Request policing (proxy_plc_xxx) - Check for nimda requests - Per-Request IP-based Access Control - Certificate Mapping and Authorization - Redirect if matched with proxy_redirect_by - Simple basic authentication - Form based authentication - Switch to tunneling if SSLVPN - Redirect if matched with proxy_redirect_by (when "-2" is used) - Serve local files if "/_intmenu/xxx" - Serve monitoring request - Reverse-proxy request to backend if matched with proxy_pass_by IPv4 <-> IPv6 ============= You need a separate binary of Orenosp to use IPv6 (orenospXXXi6.exe). Limitations in the Current Release ---------------------------------- These will be addressed in future release as demand for IPv6 grows. - SSL Portforwarding over IPv6 is not supported Especially, tnapplet (Java) is not IPv6-enabled. Other components may work but not tested yet. - Load-Balancing to IPv6 backend servers is not supported This is because the load-balancing feature requires ping (ICMPv6) functionality but it is not quite implemented yet. Publish HTTP Servers within a IPv4-LAN to IPv6 network ------------------------------------------------------ # proxy_listen_name = lis-ipv6 ::@80 http #

proxy_pass_by = lis lis-ipv6 127.0.0.1 Publish HTTP Servers within a IPv6-LAN to IPv4 network ------------------------------------------------------ # proxy_listen_name = lis-ipv4 0.0.0.0@80 http #

proxy_pass_by = lis lis-ipv4 [::1] -hh=127.0.0.1 The notation of "[]" is used to specify an IPv6 address in the host part of a URL. URL Orenosp http://[fe80::203:2fff:fe02:c640]/ -> [fe80::203:2fff:fe02:c640] http://[fe80::203:2fff:fe02:c640]:81/ -> [fe80::203:2fff:fe02:c640]:81 Name Resolution - About DNS setup --------------------------------- To pulish an IPv6 server to IPv4 network DNS entries IP addresses(A) host1.mycompany.com host2.mycompany.com Set up this way, Orenosp is able to route requests based on virtual hostnames. To pulish an IPv4 server to IPv6 network DNS entries IP addresses(AAAA) host1.mycompany.com host2.mycompany.com Set up this way, Orenosp is able to route requests based on virtual hostnames. To accept requests from both IPv6 and IPv4 networks host1.mycompany.com A host1.mycompany.com AAAA host2.mycompany.com A host2.mycompany.com AAAA Also you need to add PTR records for IPv6, but it's out of scope of this document. Misc ---- - Note about "localhost" When you install IPv6 stack on Windows XP or Windows 2003, it seems like that the first IP address that the OS returns for "localhost" is IPv6 loop back address (::1), not IPv4 loop back address (127.0.0.1), even though "127.0.0.1 localhost" is in etc/hosts file. You can try "ping localhost" to see which address it's pinging. This will cause many problems including Orenosv. Use 127.0.0.1 instead of "localhost" whenever you have a strange problem. - To specify a link-local address as a listen port, append interface number as scope-id: # in case of IPv6 link-local address, append interface number # following '%'. proxy_listen_name = lis-ipv6 fe80::203:2fff:fe02:c640%3@8888 http # ^^ You can obtain the interface number by either of the commands: >ipv6 if (XP SP0) >netsh ??? (XP SP1 or higher, Win2003) - To specify a link-local address as a connect address (URL), do NOT specify the interface number: [fe80::203:2fff:fe02:c640%3]:81 ^^ DON'T DO THIS Proxy-Backend Communication =========================== Passing Client IP Addresses to Backend Servers ---------------------------------------------- Many HTTP reverse proxies including Orenosp will add the following headers to client request: X-Forwarded-For: X-Forwarded-Host: X-Forwarded-Proto: <"http"-or-"https"-of-client-request> If you are using Apache as a backend server, you can use a module called "mod_rpaf" to make the Apache server to 1) accept X-Forwarded-For:'s IP address as real client's IP address, 2) accept X-Forwarded-Host:'s value as real virtual hostname. X-Forwarded-Proto header is introduced in Orenosp 0.7.4c and Orenosp-specific. Passing Client Certificate Information to Backend Servers --------------------------------------------------------- - Passing the whole client certificate to a backend server via a special request header When you want to send client certificate to backend server as a header value. set the following parameter: proxy_cert_pass_whole = X-CERT_BASE64 Then base64-encoded text of DER-format certificate is passed to a backend via X-CERT_BASE64 request header. Note that maximum length of the base64-encoded certificate must be less than 2048 bytes. Otherwise, the header value is truncated and an error message is written to event.og. - Passing partial information in client certificate to a backend servers. Not implemented yet. Adding Arbitrary Request/Response Headers ========================================= You can add arbitrary request/response headers in reverse proxy. Use "-rq_hdr" and "-rs_hdr" options in proxy_pass_by parameter. -rq_hdr : add request header client ---> Orenosp ---> backend here -rs_hdr : add response header client <--- Orenosp <--- backend here Simple Content Rewrite ====================== If you use any reverse-proxy, you can no longer use "absolute URLs" that point to pages on the same reverse-proxied server. For example, let's say "https://www.mine.com/" is reverse-proxied to "http://internal1/" and if you write an HTML link as then, users on the Internet try to go to the internal server directly, which fails. You need to rewrite the URL as "https://www.mine.com/doc/abc.html". Orenosp and Orenosv have a mechanism to do this kind of content (response-body) rewriting. mod_filt_rwt (optimized rewrite filter) implements this content rewriting functionality. It has two sub-modules, one is simle text search-and-replace filter, the other is a regular expression-based filter. How to configure content rewrite -------------------------------- - create a config file named /rewrite_simple.conf - add rewrite rules to the config file: ---rewrite_simple.conf--- = this is a comment http://internal1/=https://www.mine.com/ http://internal2/=https://www2.mine.com/ = eof ---end of rewrite_simple.conf--- Note on format of rewrite_simple.conf: - '=' is used as the separater: = - leading '=' (i.e., empty ) designates that line as a comment. - two consective '=' ("==") specifies a literal '='. This applies only to . - add the following line to sproxy.conf: # Content Rewrite - must come after HTTP compression filter in config file proxy_filter_define = rewrite-simple mod_filt_rwt rwtype=simple mtype="text/html" proxy_filter_assign = * rewrite-simple - restart Orenosp and check event.log Different rewrite rules for multiple paths ------------------------------------------ - use "-cf=" submodule-specific parameter to specify an alternate rewrite rule file. Note that "--" designates the begining of submodule-specific parameters. example: proxy_filter_define = rewrite-simple-1 mod_filt_rwt rwtype=simple \ mtype="text/html" -- -cf=rewrite-1.conf proxy_filter_define = rewrite-simple-2 mod_filt_rwt rwtype=simple \ mtype="text/html" -- -cf=rewrite-2.conf proxy_filter_assign = /vpath-1/* ext-rewrite-1 proxy_filter_assign = /vpath-2/* ext-rewrite-2 How text matching is done in Simple Rewrite ------------------------------------------- Text matching is done without any context. If rewrite rule is XXX=999 then, aaaXXXzzz is rewritten as aaa999zzz. If using "-hname=1" submodule option, then the following rule applies. The character that follows the matched target must not be a character that can constitute a hostname. For example, if rewrite rule is server-2=www2.example.com then, these are the results: server-2a -> NOT matched and rewritten server-2.com -> NOT matched and rewritten server-2:8888 -> matched and rewritten as www2.example.com:8888 server-2/path -> matched and rewritten as www2.example.com/path Trouble shooting ---------------- - Rewrites not working when called from browsers, but they work if I directly call the server with "telnet" command. -> Most likely your backend server is applying HTTP compression to the content. Orenosp doesn't decompress already compressed documents in order to apply filters. Make sure you do not apply HTTP compression to those contents. Since 0.4.3c, you can set "proxy_origin_gzip_disable = 1" to disable backend's HTTP compression. You should let Orenosp handle HTTP compression instead. Note: Orenosp can handle chunked-encoded response from a backend and "de-chunk" it. - If an HTML line are longer than 30KB bytes, the rewrite filter splits it in multiple chunks that are smaller than 30KB and work on each of them. If the string you want to rewrite happens to be in the middle of that split, the rewrite won't work. -> Make sure your HTML lines are less than 30K bytes. - Enabling trace : Setting rewrite trace level to 2 or 3 may help. (event.log will be very messy!) proxy_filter_define = rewrite-regex mod_filt_ext int=rewrite_regex \ mtype="text/html" -- -cf=rewrite-2.conf -trc=2 Regular Expression Based Content Rewrite ======================================== The configuration is basically very similar to that of Simple Content Rewrite. Refer to the above section for more info. - create a config file named /rewrite_regex.conf - add rewrite rules to the config file: --- rewrite_regex.conf --- = Header (]*>)=$1

Header Something

= Footer ()=

Footer Something