Users' Guide to Orenosv

for versions 1.1.3 or later.


Contents
--------
- Notation

- HTTP
 - enabling PHP
 - enabling PERL
 - enabling SSI
 - enabling CGI
 - customizing directory index
 - enabling bandwidth control
 - controlling output buffering
 - enabling security
 - enabling HTTP compression
 - enabling content rewrite
 - enabling virtual hosts
 - configuring access log
 - setting up rotating access logs
 - enabling custom error message files

- FTP
 - basic configuration
 - ftp admin module on HTTP
 - access logs
 - virtual paths (directory aliases)
 - setting up anonymous account
 - setting up normal user accounts
 - setting up access control
 - enabling bandwidth control
 - setting up user message files
 - setting up ftp server behind NAT
 - setting up FTP over SSL
 - Client Certificate Mapping and Authorization
 - enabling One Time Password (OTP)

- Using Network Drives

- OS-Integrated Authentication and Authorization
 - OS authentication (os_auth)
 - OS authorization (os_acl)
 - Anonymous user and os_acl
 - os_acl and network drives

- Per-process OS security


- Managing Orenosv Server
 - main console
 - ftp admin module
 - obfuscating passwords in passwd.txt
 - using md5-hashed passwords in passwd.txt
 - using encrypted passwords in passwd.txt
 - allowing users to change their own passwords
 - master password

- HTML Files Application


- IPv6 issues



Notation
========

ORENOSV_HOME : the directory to which you installed orenosv server software.


HTTP Service
============

virtual paths (directory aliases)
---------------------------------

Virtual paths (or directory aliases) are specified with http_doc_alias
paramter.

Note: Orenosv is basically case-sensitive.

example

  physical path: c:\Data

                    virt. path phy. path
  http_doc_alias =  /data      c:\data
                                  ^----- has be "Data"


Virtual paths in access control are only the exception to this rule.

  example
  http_auth_assign = /private ...

  Not only "/private/..." but also "/Private/..." and "/PRIVATE/..."
  matches with this line.


enabling PHP
------------

- install PHP4 for Win32 to a directory. (assume it's c:\progs\php4 in here)
  Please note that Orenosv requires "cgi.force_redirect = 0" in php.ini.


- define PHP handlers. 

  CGI handler - uncomment out this line
  #http_handler_define = cgi-php     mod_cgi     c:/progs/php4/php.exe

  ISAPI handler - uncomment out this line
  #http_handler_define = dll-php    mod_isapi   c:/progs/php4/sapi/php4isapi.dll

  You can uncomment both lines.
  Please don't forget to adjust paths to EXE/DLL to suit your environment!


- map URLs to either of two PHP handlers defined above

  to use ISAPI handler, uncomment this
  #http_handler_assign = *.php          dll-php

  to use CGI handler, uncomment this
  #http_handler_assign = *.php          cgi-php

  Note you have to choose only one to uncomment in the above example.
  Reboot the main server, try to access a PHP script and check event.log
  for any errors.

  ---- That's it.  Read on below only if you want to do complex things. ----



- If you want to use CGI version for some part of your website and
  use ISAPI version for other part of your website, use different
  URL patterns.

  http_handler_assign = /myapp1/*.php           cgi-php
  http_handler_assign = /phpgroupware/*.php     dll-php

- If you want to use separate processes for executing ISAPI version of PHP,
  specify process group in your http_handler_assign line.

  http_handler_assign = /phpgroupware/*.php dll-php  pg=pg-default

  Read Proces Group sections in the config file for defining a process
  group.


  There's more info on various configurations in default config file.


  -- Advanced: multiple versions of PHP ---
  MS Windows basically don't allow multiple versions of a single application
  to coexist.  However you follow the instructions below you can install
  multiple versions of PHP and specify which version to use.  Note that
  a single instance of Orenosv can only use a single version of PHP.

  Let's say that we are installing PHP 4.2.1 into c:\progs\php421.
  - unpack php zip file into a install directory, from here refered to
    as <PHP42_HOME>.
  - collect all DLLs that your PHP require under <PHP42_HOME>.
    - copy <PHP42_HOME>\sapi\php4isapi.dll to <PHP42_HOME>
    - for required DLLs under <PHP42_HOME>\dll\ (those that you use to copy to
      \Winnt\System32), you should copy them to <PHP42_HOME>.

  - in http.conf specify <PHP42_HOME>/php4isapi.dll as PHP ISAPI handler.
    also add "-alt=1" option to it.

    # PHP ISAPI
    http_handler_define = dll-php   mod_isapi  -alt=1 c:/progs/php421/php4isapi.dll

  - to use CGI PHP, specify <PHP42_HOME>/php.exe as PHP CGI handler.
    also add "-env=all" option to it.

    # PHP CGI
    http_handler_define = cgi-php    mod_cgi  -env=all c:/progs/php421/php.exe

  - create php.ini under <PHP42_HOME>.  use the environment variable PHPRC to
    specify path to that php.ini.

    # set environment variable
    env_add = PHPRC=c:\progs\php421

  - naturally, you will change the following php.ini parameters appropriately.

    extension_dir = c:\progs\php421\extensions
    include_path = ".;c:\progs\php421;c:\progs\php4\pear"
    error_log = c:/progs/php421/errors.log

  If configured as noted in the above,
  - all required DLLs for PHP 4.2.1 are located under c:/progs/php421.
  - to change the PHP version that your Orenosv will use, you can just 
    change the following parameters in http.conf:
    - env_add = PHPRC=... parameter
    - http_handler_define's for PHP
    or you can create another Orenosv instance to use another PHP version.



enabling PERL
-------------

  Basically, the same as PHP.
  shbang (e.g., #!/usr/local/bin/perl) line in individual Perl script
  is ignored.

- Install ActivePerl for Win32.  We'll assume you install it in c:\Perl.

- define Perl handler

  CGI handler - uncomment out this line
  #http_handler_define = cgi-perl    mod_cgi    perl.exe

  ISAPI handler - uncomment out this line
  #http_handler_define = dll-perl   mod_isapi   c:/perl/bin/perlIS.dll

  you can uncomment both lines.
  Be sure to correct paths to EXE and DLL to suit your environment.

- map URLs to either of two Perl handlers defined above

  to use ISAPI handler, uncomment this
  #http_handler_assign = *.cgi          dll-perl

  to use CGI handler, uncomment this
  #http_handler_assign = *.cgi          cgi-perl

  You can uncomment only one of the two assign lines.
  If you want to execute .pl files also as Perl scripts, map *.pl
  to Perl handler.

  #execute *.pl scripts with CGI Perl
  #http_handler_assign = *.pl          cgi-perl

  Reboot the main server, try to access a Perl script and check event.log
  for any errors.

  
trouble shooting PHP/Perl problems
----------------------------------

- CGI perl
  Error messages that are written to stderr will go to main server's
  error.log.

- ISAPI Perl
  Error messages will go to $PERLDIR/bin/PerlIS-Err.log.

- PHP
  Depends on settings in php.ini:

  log_errors = on ;
  error_log = <path-to-logfile> ;

  if set up this way, error messages will be written to <path-to-logfile>.


Tips on PHP Windows
-------------------

[limits]
php.ini
max_execution_time = 1000 ; Maximum execution time of each script, in seconds
max_input_time = 1000 ; Maximum amount of time each script may spend parsing request data
memory_limit = 8M       ; Maximum amount of memory a script may consume (8MB)
post_max_size = 100M    ; Maximum size of POST data that PHP will accept.
upload_max_filesize = 100M ; Maximum allowed size for uploaded files

http.conf mod_cgi
-x=900 : max execution time of php.exe


[Windows-specific]
php.ini
session.save_path  = c:\temp
extension=php_gd2.dll ; use this ext for GD 2.x.


enabling SSI
------------

- Currently SSI is implemented as a CGI program.
  Because of this, there are some restrictions on usage of "virtual"
  attribute.

  Supported commands and their attributes:

  o #config { timefmt="<timefmt>" | sizefmt="<sizefmt>" }

  o #echo { var="<varname>" }

    <varname>: All CGI variables and
               DATE_LOCAL,DATE_GMT,DOCUMENT_NAME,DOCUMENT_URI

  o #include { file="<fpath>" | virtual="<vpath>" }

  o #flastmod { file="<fpath>" | virtual="<vpath>" }

  o #fsize { file="<fpath>" | virtual="<vpath>" }

  o #exec { cmd="<cmdpath>" }
    NOTE: this command needs to be enabled explicitly by giving 
    "-exec_cmd" option to cgissi.exe.

  o #exec { cgi="<URL>" }
    NOTE: this command needs to be enabled explicitly by giving 
    "-exec_url" option to cgissi.exe.


  for SSI usage, please refer to the following page:
  http://hoohoo.ncsa.uiuc.edu/docs/tutorials/includes.html
  

- CGI SSI is already enabled in default http.conf.
  If you want to change its config or disable it totally,
  look for the following lines in http.conf.

  ---
  http_handler_define = cgi-ssi     mod_cgi     -x=15 cgissi.exe

  http_handler_assign = *.shtm         cgi-ssi
  http_handler_assign = *.shtml        cgi-ssi
  ---

  For example if you want to enable "#exec" command, change the line
  of "http_handler_define" to:

  http_handler_define = cgi-ssi     mod_cgi     -x=15 cgissi.exe -exec


- Options to cgissi.exe

  cgissi.exe [-exec|-exec_cmd] [-exec_url] [-incl_url]

  -exec or -exec_cmd : enable #exec cmd="<cmdpath>" command.
     if not enabled, #exec cmd= cannot be used.

  -exec_url :          enable #exec cgi="<URL>" command.
     if not enabled, #exec cgi= cannot be used.

  -incl_url :          enable #include virtual="<URL>" functionality.
     if not enabled, #include virtual= can only be used for including
     local files, but not from URL.

  <URL> can be either
    - full URL, e.g., "http://localhost:8888/test.cgi"
    - local absolute virtual path, e.g., "/test.cgi"
    - local relative virtual path, e.g., "test.html"

  In all cases, cgissi program executes a full HTTP transaction to
  fetch the requested resource, independent from the original request.
  That is, cgissi will not forward any request headers sent in from the
  original request.  If the resource to be fetched requires username/passwd,
  specify "http://username:passwd@localhost:8888/test.cgi".




enabling CGI
------------


customizing directory index
---------------------------


enabling bandwidth control
--------------------------

  Let's assume that you have upstream of 128Kb (Kilo Bits).
  and you want to restrict bandwidth of your MP3 download area to 64Kb.
  With 64Kbps, you can probably do 6KB (Kilo Bytes) per second.

- define a bandwidth group of 6KB/sec

  #                <name> <bandwidth>
  http_bw_define = music   6K

- map requests to MP3 area to the bandwidth group defined above

  #                <url-pattern>   <bw_group>
  http_bw_assign = /mymusic/*.mp3  music
  http_bw_assign = /mymusic/*.MP3  music


  Configured like the above, all the connections requesting MP3 files
  share the same bandwidth of 6KB/sec.  In other words, the bandwidth
  is distributed among all the connections.
  Note that this bandwidth scheduling is not fair in any sense.

  1) One connection on a fast link and one connection on a slow link.
  The faster connection can consume large portion of the allotted
  bandwidth while the slow connection will be left with any remaining
  bandwidth.

  2) N connections from one host and one connection from another host.
  The speed of the link is the same between the two hosts.
  The first host consumes bandwidth N times larger than the second host.
  Typical is a specialized downloader program that does "divide and download"
  scheme.

  To solve both problems, another option is introduced.

  Limit Per Host:
  Bandwidth in a bandwidth group is distributed fairly with regard to
  each client host.  To continue with the previous example, if 3 PCs are
  downloading MP3 files, each of them can download at maximum speed of
  6K/3 (= 2KB), regardless of how many connections a PC is using.

  To use this options specify "-pip" (Per IP) like:
  
  #                <name> <bandwidth> <option>
  http_bw_define = music   6K         -pip


  This limit is enforced dynamically, so if other PCs join this bw group
  while the two PC are already downloading,  limit per host will be 
  reduced accordingly.


  Note that using this option may make your bandwidth under-utilized.
  Consider a PC on 8Mb ADSL line and another PC on 56Kb modem line,
  and they are downloading 64KB-throttled contents.  Each PC gets 
  32KB of bandwidth, but the PC on analog modem can only download
  at 5KB, so the remaining 27KB is not used.
  To solve this problem the web server must find an effective bandwidth
  of a host and calculate limit per host for each host.  This is not
  implemented.

  
enabling security
-----------------
You define access restriction with http_auth_define parameter.  Then you
assign the defined access restriction to virtual paths.  One access
restriction definition can be assigned many times to different virtual paths.
An access restriction definition is called "auth handler".

Let's say you want to restrict access to the virtual directory, /private,
and all files and directories under it.

filesystem path:  c:\www\private
virtual path:     /private

There are basically three methods for restricting access.
In all cases you start by defining an "auth handler",
then specifiy the auth handler just defined for the path you want to protect.

1) restrict access by client IP addresses
  You restrict access based on client's IP addresses.

  #                  <auth-name> <auth-module> <parameters>
  http_auth_define = ip_trusted  mod_auth_ip   [allow-IP-address-list]

  allow-IP-address-list is a list of IP address, delimited by a space.
  Note that a wildcard is not allowed, i.e., you cannot specify an address
  like 123.456.789.*.

  Finally, specify just defined auth handler in http_auth_assign, like:

  http_auth_assign = /private/  ip_trusted


2) restrict access by a single password
  This is a simple and quick way of protecting pages by a password.
  A user is prompted to enter username and password but only password
  is verified.

  #                  <auth-name> <auth-module> <parameters>
  http_auth_define = fl_admin    mod_auth_file  passwd=Your_Password

  http_auth_assign = /private/  fl_admin


3a) restrict access by user names and their passwords
  In this case, you must supply a user-password file for authenticating
  users.  For format of user-password file, see provided sample passwd.txt
  file.  A user is allowed access if 1) his user name is in the password file
  and 2) the password he sends matches the password in the password file.

  #                  <auth-name> <auth-module> <parameters>
  http_auth_define = fl_valid  mod_auth_file id=passwd.txt allow="_valid_"

  Finally, specify:
  http_auth_assign = /private/  fl_valid


3b) restrict access by users' groups
  In addition to the password file authentication, you must supply
  a group file for authorizing access.  For format of group file,
  see provided sample grpdb.txt file.


  #                  <auth-name> <auth-module> <parameters>
  http_auth_define = fl_pictures  mod_auth_file id=passwd.txt grp=grpdb.txt \
                     allow="@family,@my_friends,@her_friends,myname"

  In "allow" parameter you specify a list of group names and/or user names
  to allow access.  Each name must be delimieted by ','.
  A group name must be preceded by '@' character.

  A user is allowed access if
  1) his username is in the password file, and
  2) the password he sends matches the password in the password file, and
  3) one of the following is true
    3a) his username is in "allow" list, or
    3b) his username is a member of a group name which is in "allow" list.

  Finally, specify:
  http_auth_assign = /private/  fl_pictures


Misc info
- in cases 2,3a,3b you can specify a realm name, which you can use
  to show a message in user's password prompt box.
- you can specify a combination of two auth handlers in one http_auth_define
  parameter, connected with either & (AND) or | (OR).
- see provided sample http.conf for more info on these.



enabling HTTP compression
-------------------------

  Let's assume that you want to compress text files only, both static and
  dynamic.  By "text" files, I mean plain text and HTMLs.

  CAUTION: pay close attention to what media types you are compressing.
  I found that some file types such as PDF have problems when compressed.
  Also found that Netscape 4.7x can't handle compressed JPEG files.
  Do test with all browsers/plugins that you are going to support before
  you start compressing file types other than HTML and TXT.


- define compression filter(s)

  find the following lines and uncomment them if not already.

  http_filter_define = comp-uncond  mod_filt_zlib
  http_filter_define = comp-txtonly mod_filt_zlib    mtype="text/,audio/midi"

  
- map requests to filters defined above

  Find and uncomment these lines:

  #http_filter_assign = *.html comp-uncond
  #http_filter_assign = *.txt  comp-uncond

  #http_filter_assign = *.php  comp-txtonly

  The third line tells the server not to compress any non-text data
  (image or binary data) that PHP scripts might generate.
  (because these kinds are usually compressed already).


- alternative method

  compression filter (mod_filt_zlib) can conditionally compress data stream
  based on its mime type.  Therefore the next line alone can achieve
  the same effect.

  # everything goes through compression filter
  htttp_filter_assign = *  comp-txtonly

  However you want to avoid making everything go thru the filter
  because of its overhead, especially static files that don't need
  compression should not go thru the filter for performance.


enabling content rewrite
------------------------
  Please refer to Orenosp Users Guide.
  http://hp.vector.co.jp/authors/VA027031/orenosp/guide_en.txt
  (see Content Rewrite section)


enabling virtual hosts
----------------------

Let's say you already have a server name, www.myserver.com, and now
you want to host a virtual host, www.myfamily.com.

- Get the new domain name registered.

- Make a new directory somewhere under your htdocs, that will contain
  all files for the new vhost.

  > mkdir <ORENOSV_HOME>\htdocs\vhosts
  > mkdir <ORENOSV_HOME>\htdocs\vhosts\myfamily

- Add the following line to your http.conf.

  http_vhost_dir = www.myfamily.com  /vhosts/myfamily

- Use "/vhosts/myfamily" as path pattern for other settings in http.conf
  for this particular vhost.

  For example if you want to restrict access to the new vhost,
  specify like this:

  http_auth_assign = /vhosts/myfamily/  fl_myfamily

  This will restrict access to both:
    http://www.myfamily.com/*
    http://www.myserver.com/vhosts/myfamily/*


  Another example is to limit network bandwidth that this virtual
  host can use:

  #                <name>       <bandwidth>
  http_bw_define = bw_myfamily  32K
  #                <url-pattern>           <bw_group>
  http_bw_assign = /vhosts/myfamily/*      bw_myfamily


- IP/port-based virtual hosting?

  IP/port-based virtual hosting is not supported in Orenosv.  Please use
  Orenosp Secure Reverse Proxy with Orenosv to accomplish this.

  [ a paragraph not translated yet ]

  ---sproxy.conf---
  # listen on second NIC, 192.168.1.200, port 80.
  proxy_listen_name = http-host2  192.168.1.200@80  http
  # pass all requests on http-host2 to http://localhost:8888/ with Host header
  # of "host2"
  proxy_pass_by = lis http-host2  localhost:8888 -hh=host2

  ---http.conf---
  http_vhost_dir = host2   /vhosts/host2



configuring access log
----------------------

Orenosv supports the following four log format for http access log.
Set desired format in http_log_access_fmt parameter.

- Access log formats

 common : common log format(CLF)
   host rlogname ruser [time] "request" status bytes

 common-vhost : CLF w/ vhostname
   vhost host rlogname ruser [time] "request" status bytes

 combined : NCSA combined
   <common> + "Referer" "User-Agent"

 combined-vhost : combined w/ vhostname
   <common-vhost> + "Referer" "User-Agent"


These log formats, especially the first three, are very popular
among Apache installations, so they should be compatible with many
log analysis tools.


Furthermore you can additionally specify detailed format settings
using http_log_access_flags parameter.

 http_log_access_flags = <bit_flags>

 <bit>
 0001  : record server vhostname in logname column (2nd column)
 0002  : resolve client ip address into hostname (1st column)



setting up rotating access logs
-------------------------------
To periodically rotate access log files while the service is running,
you can use an Apache-compatible piped logging programs.

Note: Although this method is flexible, it is not optimal from performance
standpoint.

There are currently two programs that have been confirmed to work.

1) rotatelogs.exe from Win32 Apache distribution
   rotatelogs.exe in Apache 2.0.x will work.

2) Orenosv-enhanced rotatelogs-char.exe
   Based on rotatelogs.c in Apache 2.0.x, the following features have been
   added:
   - switch log when a day, week, or month changes.
   - at log switch, it can start a program to post-process the old log file
     (for example, to compress and archive the log to somewhere).

   You can obtain this from http://hp.vector.co.jp/authors/VA027031/orenosv/.


Procedures to set up
- copy rotatelogs.exe from a Win32 Apache distribution or rotatelogs-char.exe
  to <ORENOSV_HOME>.

- instead of http_log_access, use http_log_access_io parameter.

  http_log_access_io = pipe rotatelogs <options-to-rotatelogs...>

  for options to rotatelogs, follow this URL.
  http://httpd.apache.org/docs-2.0/programs/rotatelogs.html


example 1 (using Apache rotatelogs)

  - switch logs once a week (60*60*24*7 = 604800secs)
  - create log files with dates in filenames
  - timezone of the server host is in JST(GMT+9:00)  (60*9 = 540mins)
    (if PST(GMT-8:00), use -480)

  http_log_access_io = pipe rotatelogs \
                       "c:/log files/access-%Y%m%d.log" 604800 540

  Most filenames must be encloed by double quotes.


  - switch log at every 8-hour interval everyday (0:00,8:00,16:00)
  http_log_access_io = pipe rotatelogs \
                       "logs/access-%Y%m%d-%H%M%S.log" 28800 540

  - switch log when the current log file exceeds 1M bytes
  http_log_access_io = pipe rotatelogs \
                       "logs/access-%Y%m%d-%H%M%S.log" 1M



example 2 (using Orenosv rotatelogs-char)
  Assume that you renamed rotatelogs-char.exe to rotatelogs.exe.

  - switch log at 0:00 on every Sunday
  http_log_access_io = pipe rotatelogs "logs/access-%Y%m%d.log" -cal:week

  - switch log at 0:00 on every Monday
  http_log_access_io = pipe rotatelogs "logs/access-%Y%m%d.log" -cal:weekmon

  - switch log at 0:00 on every 1st day of month
  http_log_access_io = pipe rotatelogs "logs/access-%Y%m%d.log" -cal:month

  - switch log at 0:00 everyday
  http_log_access_io = pipe rotatelogs "logs/access-%Y%m%d.log" -cal:day



enabling custom error message files
-----------------------------------
System-default error messages are stored in ORENOSV/mesg directory.
Filenames are in the following format:

  NNN_XX.html
  NNN.html

  NNN represents 3 digit error number(HTTP status) and XX represents
  a language specifier sent from the browser (Accept-Language).
  First language-dependent message file (NNN_XX.html) is looked for,
  and if not found, then language-independent message file (NNN.html) is
  looked for, which usually contains English messages.

In order to customize error message files, please follow next
procedures rather than directly editing mesg/*.html.

- make a new directory under ORENOSV_HOME.  Let's say it's
  ORENOSV_HOME/mymesg.

- create your own error message files in "mymesg" directory 
  following naming convention of NNN_XX.html or NNN.html.

- add following parameter in http.conf

  http_emf_dirs = mymesg:mesg

  Set this way, the server first searches "mymesg" directory and if can't
  find a proper error message file, it searches "mesg" directory.



FTP Service
===========

basic configuration
-------------------

 - enable FTP service in http.conf

   ftp_enable = 1 


 - decide which IP address and port number to use for FTP service.

   for the port number, you should use standard FTP port, 21.
   for the IP address, unless you have a specific need, use 0.0.0.0.
   Thus the following is the default:

     ftp_listen = 0.0.0.0@21

   From version 0.4.4, you can specify multiple ftp_listen parameters.


 - decide which directory will be the global root directory for
   all FTP users.

   if you want make the web document space available for FTP users, specify:
   
     ftp_doc_root = htdocs

   this directory will be relative to your http_server_root (which is
   by default ORENOSV_HOME).

   or you can point to the area for IIS's ftp service:

     ftp_doc_root = c:/inetpub/ftproot


 - set resource limits

   max number of sessions

     ftp_sess_max = 20

   idle session timeout in seconds

     ftp_sess_timeout = 60


 - set up minimum access control

     ftp_acl = /      ALL="_valid_"

   This will allow all users (in passwd.txt) to read and write
   any files in the entire ftp virtual directory hierarchy.

   To actually allow clients to login, go to either
   "setting up anonymous account" or "setting up normal user accounts"
   sections and follow instructions there.


 - [recommended] set up ftp admin module on HTTP service

   You can set up ftp admin module on the main HTTP service to monitor
   FTP service status and kill unwanted sessons and/or transfers.

   Put the following in your http.conf (they are already in http_ftp.conf)

   # set up FTP status page on HTTP main server
   http_handler_define = ftpadm     mod_ftpadm
   http_handler_assign = /ftpadm    ftpadm  np=+
   http_auth_assign =  ! /ftpadm    ip_localhost
   http_auth_assign =  ! /ftpadm    fl_admin

   Also put the following in your admin.conf (if it's not already)

   http_admin_auto_ftpadm_proxy = "http://any:admin@127.0.0.1:8888"

   (The above assumes that ftpadm handler in your main server is accessible
   via URL of "http://any:admin@127.0.0.1:8888/ftpadm".)

 
 - [optional] port number of data connection in PORT mode

   The FTP spec (RFC959) states that port number of data connection in 
   PORT mode should be set to 20.  Orenosv by default doesn't follow this rule.
   If you want to conform to this spec, use:

   ftp_port_srcport = 20

   Also you can specify an negative integer (e.g., -1) for multiple listen
   ports environment.  See http_ftp.txt for details.


access logs
-----------
  By default, two kinds of access logs are generated.  

  - ftp_session.log
    Records login-related events
  - ftp_access.log
    Records execution of commands.
    Rou can specify which commands will be logged by using ftp_log_access_cmds
    parameter.


  Both logs can be totally disabled by specifying empty filename
  in the parameters.  To disable ftp_session.log, write:
  
    ftp_log_session = 

  in http.conf.


  Rotating access log files
  Just like HTTP access logs, you can rotate FTP access logs while the service
  is running.  Instead of ftp_log_access, use ftp_log_access_io parameter.
  Value of the parameter is the same as that of http_log_access_io, so see
  the explanation of that parameter.

  ftp_log_access_io = pipe rotatelogs \
                      "c:/log files/ftp-access-%Y%m%d.log" 604800 540

  Rotating session log files
  Use ftp_log_session_io in place of ftp_log_access_io.


  Record Format in Access logs
  logged in common log format (CLF).


  Record Format in Session Logs 
  Note: Since 0.8.1, session log format includes event id.  You can now rely on
  the event IDs rather than parsing textual messages.

  <date-local> <time-local> <sess-slot> <sess-seq> <event-id> <client-ip> <message>

  date-local : YYYY/MM/DD local time
  time-local : HH:MI:SS local time
  sess-slot  : session id slot number
  sess-seq   : session id sequence number:
              (slot#, seq#) makes non-repeating session IDs
  event-id   : numerical code that identifies the event
  client-ip  : client IP address
  message    : textual message


  Event IDs
  1    user logged in (auth'ed)
  6    logout auth user
  7    logout non-auth user

  11   authentication failed
  12   root dir does not exist
  13   concurrent logins exceeded
  14   concurrent logins per host exceeded

  21   certmap: certificate mapped to username
  22   certmap: certificate not mapped to username
  23   certmap: no certificate to map


virtual paths (directory aliases)
---------------------------------

  Just like the HTTP server, you can use directory aliases to form
  virtual paths.  You will build FTP virtual filesystem using 
  "ftp_doc_root" parameter and multiple of "ftp_doc_alias" parameters.

  example-1)  make available drive G: as whole

    #               virtual-path   real-path
    ftp_doc_alias = /drive-g       g:/

  Note that these virtual paths will not be listed in directory listing,
  so you should give out the URL like ftp://your-host/drive-g/files.

  example-2)  make space available for anonymous user

    # for anonymous ftp
    ftp_doc_alias = /pub             e:/ftpusers/pub

  You also need to enable anonymous account if you want anonymous access.


  --- Fake directory ---
  Since version 0.5.5, there is a way to list directory aliases in
  directory listings.  Note that this is just a hack and will be replaced
  with more consistent and secure method in near future.

  Example
  ftp_doc_root = c:/ftproot
  ftp_doc_alias /d-drive   d:/
  you want to list d-drive in directory listing of /.

  steps to take
  - add to config file : ftp_fakedir_enable = 1
  - Using Windows Explorer, create a shortcut c:\ftproot\d-drive.lnk
    that links to d:\.

  Remember that you have to set up ftp_doc_alias in addition to creating
  the shortcut.
  Note that you should make the parent directory of the alias (/ in the above)
  READ-ONLY to normal users for security.


setting up anonymous account
----------------------------

- enable anonymous account by setting:

  ftp_anon_enable = 1

- you can restrict anonymous user's scope to a limited portion
  of the global virtual directory hierarchy.  To do this, you will
  use user-specific virtual root directory for the anonymous account.

  ftp_anon_uroot = /pub

  if set up this way, virtual directory /pub will be the virtual root directory
  of the anonymous account, thereby limitting the user to that directory
  or directories under it.

  if this parameter is not specified, it defaults to "/".


setting up normal user accounts
-------------------------------

- prepare passwd file (passwd.txt)

  You will need to have a password file under ORENOSV_HOME directory.
  name it "passwd.txt".

  Put username and password in this file. (put password in clear text.)
  You can add/delete users while the server is up.

  Note that you can share the password file for FTP service and
  HTTP service by specifying the same file.

  parameter ftp_iddb_file can be used to specify another file:

    ftp_iddb_file = ftp_passwd.txt

- prepare group file (grpdb.txt)

  In order to make user accounts manageable, you can group
  several users into one group.  Create a file named "grpdb.txt"
  in ORENOSV_HOME directory.
  You have to have one in ORENOSV_HOME directory even if it's empty.

  Note that you can share the password file for FTP service and
  HTTP service by specifying the same file.

  parameter ftp_grpdb_file can be used to specify another file:

    ftp_iddb_file = ftp_grpdb.txt

  
- user-specific virtual root

  Just like ftp_anon_uroot parameter, you can set user-specific virtual
  root directory for each normal user.  Specifiy it in the third field
  of the password file.

  --- in passwd.txt ---
  ftpuser2:pass2:/ftpusers/user2
                 ^^^^^^^^^^^^^^^
  if not specified, it defaults to "/".


- limit on concurrent logins per account

  You can limit number of concurrent logins per account.
  This limit will be applied to all accounts except anonymous account.
  The default value is -1 and it indicates no limit.

  ftp_clmax_default = 2

  [NOTE: this parameter is tentative and may be replaced with more
   elaborate scheme in the future.]


- limit on concurrent logins per host

  You can also limit number of concurrent logins per client host (IP).
  This limit will be applied to all hosts regardless of account names.
  The default value is -1 and it indicates no limit.

  ftp_clmax_perhost = 2

  [NOTE: this parameter is tentative and may be replaced with more
   elaborate scheme in the future.]


setting up access control
-------------------------
  With access control, you can specify which user can access (get or put)
  which files or directories.

  ftp_acl is a parameter that specifies a rule for access control.
  You can use multiple ftp_acl parameters to specify acess control rules.

  Syntax:
   ftp_acl = [!] <vpath-prefix>  <list-of-permitted-users>

  There are five permission types:
    RETR : allow downloading files
    LIST : allow listing directories
    STOR : allow uploading files
    MKDIR : allow making directories
    DELREN : allow deleting and renaming files/directories
  In addition, the following abbreviations can also be used:
    MODIFY : DELREN + MKDIR
    READ  : RETR + LIST
    WRITE : STOR + MODIFY
    ALL   : READ + WRITE


  Example-1

  #         vpath-prefix    list of allowed users
  ftp_acl = /user1/         ALL="user1" READ="@group1"
  
  For all files and directories that begin with "/user1/",
  READ permission is granted to "user1" and 
  ALL permissions (meaning both READ and WRITE) are granted to
  members of a group "group1".


  Example-2

  ftp_acl = /pub/          READ="_all_"  ALL="@admin"

  For all files and directories that begin with "/user1/",
  READ permission is granted to any user whether he is an authenticated
  user or anonymous user. ALL permissions are granted to members of 
  group "admin".
  ("_all_" is a special group that represents any user including anonymous.
  "_valid_" is a special group that represents any authenticated user.)


  Example-3  (Order of Rules)

  ftp_acl = ! /pub/          READ="_all_"  ALL="@admin"
  ftp_acl = ! /pub/incoming/ ALL="anonymous,@admin"  READ="_valid_"

  Now we will talk about the order of multiple ftp_acl parameters.
  The list of ftp_acl parameters is searched in the reverse order of
  appearing in the conf file.
  If the anonymous user tries to put /pub/incoming/myfile.txt,
  he will succeed.  Putting '/pub/myfile.txt' will fail because
  /pub/myfile.txt won't match with /pub/incoming/, thus the 1st rule
  is enforced, where he doesn't have WRITE permission.

  Note the use of '!' in front of path prefix.  Without it, the server
  will try to enforce all paramaters that match the file's pathname.
  Continueing with the above example, the user trying to put 
  /pub/incoming/myfile.txt will have to pass the first rule in 
  addition to the second rule.
  Specifing '!' will prevent the server to look further up the list.


  Example-4  (LIST & RETR permissions)

  ftp_acl =    /             LIST="_all_"
  ftp_acl = !  /customers/   RETR="@cust"

  READ permission is actually a combination of RETR(retrieve) and
  LIST(directory listing) permissions.
  In this example, a customer can get a file only if he is given
  the exact path to the file.  He cannot browse the directory for files of
  other customers.


  Example-5  (Quoting vpath-prefixes)

  ftp_acl = ! "/c/Documents and Settings/"

  If the vpath you want to specify contains a whitespace or any non-ASCII
  characters, you must enclose the vpath with double-quotes.
  Also in this example no permission is specified.  This will effectively
  shut out any user from entering "/c/Documents and Settings/" or deeper.




setting up user message files
-----------------------------

  You can specify messages that will be sent to your ftp users
  on particular events.  Message texts are stored in files and
  their pathnames must be specified in http.conf.

  Currently messages for the following events are available:

  - greeting : when a user successfully logs in 

    ftp_umf_greet = ftp_hello.txt


setting up ftp server behind NAT
--------------------------------
  If your ftp server is behind a NAT, some FTP clients have problems in
  transfer.

  The most trouble-free method is to use EPSV command, however
  not many ftp clients and ftp-aware NAT/routers use/recognize this command.

  To make ftp service available to all possible clients
  follow the instructions below.  If your server requires FTP over SSL
  it is even more likely that your clients will face this problem.


- If you are not using any D-DNS client to register your hostname,
  put these in http.conf 

  # detect WAN side IP address at 10 minute interval
  dydns_ipdetect_method = url
  dydns_ipdetect_url = http://checkip.dyndns.org/ "IP Address:"
  dydns_ipdetect_intvl = 10

  # using IP address detected by the above for PASV output
  ftp_pasv_wan_ip = detected

  # range of pasv listen ports
  ftp_pasv_port_range = 12000-12100


- If you are using a D-DNS client to register your hostname,
  put these in http.conf 

  # detect WAN side IP address by resolving my hostname at 10 min interval
  dydns_ipdetect_method = dnsname
  dydns_ipdetect_dnsname = myhost1.dydns.org
  dydns_ipdetect_intvl = 10

  # using IP address detected by the above for PASV output
  ftp_pasv_wan_ip = detected

  # range of pasv listen ports
  ftp_pasv_port_range = 12000-12100


- configure your NAT/router to

  - port-forward 21 to your server PC
  - port-forward 12000-12100 to your server PC


  Once configured as above, your ftp users should be able to transfer files
  with PASV commands.

  Regarding global IP detection methods, there are actually three options:

  1) use external site as done in the above (such as checkip.dyndns.org)
  2) use your routers status page
     If using Linksys Router, use:
     dydns_ipdetect_url = http://any:admin@192.168.1.1/Status.htm "WAN:"
     If using D-Link Router, use:
     dydns_ipdetect_url = http://admin:admin@192.168.1.1/st_devic.html "WAN"
  3) use your (D-DNS registered) hostname to detect the global IP
     This method would be easiest if you are using a D-DNS client.


- Notes

  If the NAT router (client or server side) is aware of FTP protocol,
  the setup described above is not necessary for non-SSL ftp sessions.
  You will need it only in SSL FTP sessions.
  In such a case, you can specify "-sslonly" option to ftp_pasv_wan_ip
  to indicate that value of ftp_pasv_wan_ip should be honored only
  in SSL FTP sessions.

    # use WAN IP address for PASV output in SSL sessions only
    ftp_pasv_wan_ip = -sslonly detected


  Generally a data connection must be created on the same network interface
  as the control connection.
  Using ftp_pasv_wan_ip makes it possible for you to set up otherwise.
  Please be sure to avoid it.


Setting up FTP over SSL
-----------------------

  - Prepare a server certificate and its private key in PEM(text) format.

    Orenosv comes with a server certificate and private key solely for
    testing purposes.  The pass phrase for this private key is "orenosp".
    Do not use this certificate except for testing purposes.

    You can generate your own certificate or request one from a commercial
    CA the same way as you would do for Apache+mod_ssl.

  - Name the server certificate as server.crt and place it under
    <ORENOSV>/ssl.crt/server.crt.
    Name the server private key as server.key and place it under
    <ORENOSV>ssl.key/server.key.

  - Put the following config in http.conf

    # enable FTP over SSL
    ftp_ssl_enable = 1

    # put passphrase for server private key in clear text
    ftp_ssl_keypass = <your-passphrase-for-server-key>


    There are two alternative methods to specifying the passphrase in clear
    text.

    a) specify the passphrase as the master password to Orenosv.

       ftp_ssl_keypass = !masterpwd

       !masterpwd is a special keyword that tells the server to use
       the master password as the passphrase for server private key.

    b) encrypt the passphrase for server private key with the master
       password, and paste that ciphertext in ftp_ssl_keypass.

       Encrypt pass phrase
       > cgipasswd -util encrypt -mp <master-pwd> passwd-for-server-key
       cipher-text = $A$AAjk...
                     ^^^^^^^^^^ 
       Paste this into http.conf
       ftp_ssl_keypass = $A$AAjk...


    The master password can be specified as a service parameter when
    starting up Orenosv service.  Please refer to "Master password" section
    for more on it.


  - If you want to enforce SSL on users

    # enforce SSL use on all users including anonymous
    ftp_ssl_require = _all_

    # enforce SSL use on all users except anonymous
    ftp_ssl_require = _valid_

    # enforce SSL use per user
    ftp_ssl_require = user1,user2,user3

    Note: you cannnot specify a group name (@group1).


  - Now your clients can connect to the server using "Explicit FTP over SSL".
    There is a list of tested FTPS clients programs in ftps.html.

  - If you want to set up "Implicit FTP over SSL", configure a separate
    listen port for FTPS, label it as "ssl".

    # regular FTP 
    ftp_listen = 0.0.0.0@21
    # dedicated for implicit FTP over SSL
    ftp_listen = 0.0.0.0@990 ssl

    Orenosv can support both "Explicit FTPS" and "Implicit FTPS"
    simultaneously.

  - SSL performance tuning

    Some FTPS clients (especially those using Openssl) try to negotiate
    for the strongest and slowest encryption algorithm for SSL communications.
    
    You can specify lighter and faster RC4 algorithm  to be used for
    SSL communication by using:

    ftp_ssl_ciphers = RC4:-SSLv2


  - SSL Client Certificate Authentication,
    Certificate Mapping and Authorization

    In versions prior to 0.8.1 you can only set up SSL client authentication
    such that the server will only accept connections with valid client
    certificates.  There was no functionality to map identity of a client
    certificate to an Orenosv user.

    In 0.8.1 or later you can also use Certificate Mapping and Authorization.
    Please see the next section.


Client Certificate Mapping and Authorization
--------------------------------------------
If you are using SSL Client Authentication (i.e., clients are required to
present a valid certificate on connecting), you can also enable
Certificate Mapping and Authorization feature.

Basically, you define mapping rules between certificate and usernames,
and use the resultant username to authorize client access.

First you have to enable SSL Client Authentication.  For this, please refer
to Orenosp Users' Guide.
http://hp.vector.co.jp/authors/VA027031/orenosp/guide_en.txt
(see SSL Client Authentication section)

Then, follow the instruction below to enable certificate mapping.


Parameter:

ftp_ssl_certmap = <op-mode> <options>...

<op-mode>

none
  Certificate Mapping will not be done.

check_only
  The certificate is mapped to a username but that username will not
  be used as the implicit input to USER command.  You use this mode when
  you want to enforce access control based on certificate mapping but don't
  want to enforce certificate-username requirement.  You should use this
  mode along with "-nomap=deny" option (which is default).
  
map_to_user
  The mapped username will be used as the implicit parameter to USER command.
  The user is still required to enter a password.

no_password
  The mapped username will be used as the implicit parameter to USER command.
  The user will be allowed to log in without entering his/her password.
  You are still prompted for password but you can enter any word there.

  NOTE: if you are using os_acl option, you MUST NOT use this option.
  If you do, users will not be allowed to log in because Orenosv will not
  be able to impersonate the client user on the host OS.


<options>

-cmap=<filename>
  The default value is "certmap.txt".

-nomap=<action>
  Specify an action taken if the client control connection has no client
  certificate or the certificate is not mapped to any user.

  <action> can be:
  deny                : deny client connection to proceed.
  allow               : allow client and proceed to regular USER auth which
                        accepts any username.
  default:<username>  : map client connection to user <username>.
  The default value is "deny".


For syntax rules of certmap.txt, please see subsection
"Certificate Mapping Rules" in Orenosp Users' Guide.
http://hp.vector.co.jp/authors/VA027031/orenosp/guide_en.txt

Results of certificate mapping are logged into FTP session log.


Example-1

Require SSL client certificate.  Only allow users named "User One" and
"User Two" who are members of Orenosv Inc.  Deny all other clients.

--- http.conf ---
ftp_ssl_clauth = require

ftp_ssl_certmap = map_to_user -cmap=certmap.txt -nomap=deny
--- end ---

--- certmap.txt ---
user1  Subject  CN=User One, O=Orenosv Inc.
user2  Subject  CN=User Two, O=Orenosv Inc.
--- end ---


Example-2

Accept optional SSL client certificates.  Allow non-anonymous access
only to clients with valid and successfully mapped certificates.
Clients with no certificate or non-mapped certificates must log in as
anonymous.

--- http.conf ---
ftp_ssl_clauth = optional

ftp_ssl_certmap = map_to_user -cmap=certmap.txt -nomap=default:anonymous
--- end ---





enabling One Time Password (OTP)
--------------------------------

[To be translated later...]

Requirements
- User passwords in the password file must NOT be MD5-hashed.
  Also OS password authentication cannot be used.
  Convert the password file to either plain text or encrypted text.

- Use FTP client that support OTP-MD5.
  (e.g., SmartFTP, etc)
  Or you can use any OTP-MD5 calculator program (like Java applet).


You can enforce use of OTP per user.  You cannot enforce OTP use on
anonymous user.

examples

  Require use of OTP on all users (except anonymous)

    ftp_otp_require = _all_

  Require use of OTP on all users (except anonymous) who are on non-SSL
  connections

    ftp_otp_require = -nossl _all_

  Require use of OTP on user1 and user2 when they are not on SSL connections.

    ftp_otp_require = -nossl user1,user2


Note: Orenosv's OTP is not an true OTP as defined by OTP RFCs.
It is interoperable with standard OTP clients and generators
and I believe it's almost as secure as OTP.



Using Network Drives
====================

If you want to specify a network drive for an HTTP or FTP alias,
follow the procedure below.

1) Specify real path in a UNC path.

  e.g.,
  ftp_doc_alias = /pub2        //myserver1/ftproot

2) Run orenosv service as a user other than the default LocalSystem.

  Using the Windows service control program, set up the orenosv service to run
  as a user who has access to the network drive desired.


If you satisfy all of the following conditions, there is another way.

- effective in FTP service only
- Password entry for the FTP authenticated user has both "os_auth=1" and
  "os_acl=1".
- The version of the OS is Windows 2000 or later.

In this case, the authenticated FTP user will access the network drive
as the OS user corresponding to that FTP user.



OS-Integrated Authentication and Authorization
==============================================



OS authentication (os_auth)
---------------------------

OS authorization (os_acl)
-------------------------

Anonymous user and os_acl
-------------------------

os_acl and network drives
-------------------------

Risks using OS authentication
-----------------------------


Per-process OS security
=======================
You can execute CGI child processes and worker processes in a process group
in OS security context of another OS user.

CGI - specify mod_cgi option  -osuser=<username>:<password>

process group - in process group definition, specify
                -osuser=<username>:<password>


The specified OS user must have OS privilege (right) of "Log on as a service".
This right can be granted in "Local Security Policy" applet on Windows OS.


Also if you are running the Orenosv service as another user than LocalSystem
(default), you need to grant the following privileges to that OS user:

"Act as part of Operating System" (SE_TCB_NAME)
"Replace process level token" (TOKEN_ASSIGN_PRIMARY)

These rights can be managed through "Local Security Policy" applet.



Managing Orenosv Server
=======================

Main console
------------
Orenosv server can be remotely managed by any Web browser provided that
you make the admin HTTP server accessible remotely.
Basically it's the same process as making the main server remotely accessible.

As for the security, first thing you should do is to change default password.
To make it more secure you can wrap the server up with SSL by installing
Orenosp Secure Reverse Proxy.


FTP admin
---------
FTP admin module runs inside the main server.  When you access ftp admin
page on the main admin console, the admin server will forward
(i.e., reverse-proxy) all ftp admin requests down to the main server.
Therefore you don't need to make the main server remotely accessible
just to access the ftp admin page remotely.
If you don't need to publish any web pages, you can make the main server
to listen on 127.0.0.1 only.

Suppose your ftpadm is accessible on the main server with URL of
http://localhost:8888/ftpadm, you can set the following parameter in
admin.conf:

    http_admin_auto_ftpadm_proxy = "http://any:admin@localhost:8888"

The above assumes that ftpadm handler in your main server is accessible
via URL of "http://any:admin@localhost:8888/ftpadm".  You can adjust
port number and username/password to your setup.


If you place ftpadm handler in a different virtual path, you may have to
tell Orenosv to use an optional host header when reverse-proxying.

Let's say you put ftpadm in one of virtual hosts,

  URL - http://ftpadm.myserver.dyndns.org:7777/ftpadm

i.e., you place ftpadm in real (nonvhost) vpath of

   /vhosts/ftpadm.myserver.dyndns.org/ftpadm

Then you would put the following in admin.conf:

  # access localhost:8888 using host header ftpadm.myserver.dyndns.org:7777
  http_admin_auto_ftpadm_proxy = "http://any:admin@localhost:8888"  ftpadm.myserver.dyndns.org:7777


How a request to ftpadm is redirected:

 http://localhost:9999/monitor.adm?cmd=<http-ftp-cmd>
   is redirected to (by mod_admin in admin server)
 http://localhost:9999/ftpadm?cmd=<ftp-cmd>
   which is proxied to (by mod_proxy in admin server)
 http://localhost:8888/ftpadm?cmd=<ftp-cmd>
   this is handled by mod_ftpadm in main server



Obfuscating passwords in passwd.txt
-----------------------------------
If you put user passwords in clear text in passwd.txt, anyone who
could have access to this file can obtain all user passwords.
There are two methods to avoid this.

1) store hashed value of passwords in passwd.txt.

  Pros
  - User passwords in clear text are not accessible to the server program
    or server administrator.

  - Administrator doesn't need to set "master password".

  Cons
  - Cannot be used for various authentication methods that may be supported
    in future.  For example if HTTP digest auth is implemented, these
    password hashes cannot be used for the digest authentication.
    Also you cannot use these hashed passwords if you intend to use
    OTP in the FTP service.


2) store user passwords that are encrypted with "master password".

  Pros
  - User passwords in clear text are accessible to the server program and
    server administrator.

  - Can be used for various authentication methods that may be supported
    in future.  (like HTTP digest auth).

  Cons
  - Administrator needs to set up "master password". 
    Under a usual configuration, the admin needs to pass "master password"
    to Orenosv service at every service startup.


Using md5-hashed passwords in passwd.txt
----------------------------------------
MD5-hash passwords and store them in passwd.txt

1) put clear text passwords in passwd.txt.

2) execute the following command to batch-convert all clear text passwords
   into hashes.

  > cgipasswd -hash [-file <password-file>]

3) Since MD5 passwords begin with "$1$", Orenosv is able to detect
   them automatically.


You cannot recover clear text passwords from MD5-hashes.
To reset a password, follow the above procedure.
MD5 passwords and clear text passwords can coexist in a single passwd.txt.

Because MD5 hash format is the same as FreeBSD's crypt-md5, you can also use
the following programs for conversion:

- Crypt::PasswdMD5 packages for Perl

- Openssl "passwd -1" command 



Using encrypted passwords in passwd.txt
---------------------------------------
Encrypt passwords with master password and store them.

1) put clear text passwords in passwd.txt.

2) execute the following command to batch-convert all clear text passwords
   into encrypted passwords.

  > cgipasswd -conv encrypt -mp <master-passwd> [-file <password-file>]


3) Since encrypted passwords begin with "$A$", Orenosv is able to detect
   them automatically.  You must specify the master password to Orenosv
   service when starting up the service.

4) To decrypt all encrypted passwords:

  > cgipasswd -conv decrypt -mp <master-passwd> [-file <password-file>]

5) To show decrypted passwords on stdout (i.e., don't update passwd.txt):

  > cgipasswd -conv show -mp <master-passwd> [-file <password-file>]


Encrypted passwords, clear text passwords and MD5 passwords can coexist
in a single passwd.txt.  For example you can MD5-hash admin user's passwords
only and encrypt all other users passwords.


Password format in passwd.txt
-----------------------------

$1$xxx : md5-hashed password
$A$xxx : encrypted password
$D$xxx : unix-crypt password (DES-crypt)



Allowing users to change their own passwords
--------------------------------------------
If you protect access to your HTTP or FTP site, you will assign
an initial password for a new user account.  There are times when
you want your users to update their password to their liking.

passwd.txt is a plain text file and any change made to the file
is immediately reflected in the server.  You can create a self-service
password change form using Perl.

As a sample, a CGI program written in C is supplied.  Perl is not
required.  I will list the steps to use the sample program here.

- files

<ORENOSV_HOME>/cgipasswd.exe  password change CGI program
<ORENOSV_HOME>/htdocs/accounts/passwd.shtml  password change form in HTML
<ORENOSV_HOME>/admin/doc/cgipasswd.c  source code for cgipasswd.exe

- setup

[...]


Master password
---------------
Orenosv master password can be optionally specified as a service startup
parameter when starting Orenosv service.

Uses of master password

- as a secret key for encrypting user passwords (in passwd.txt)

- as a passphrase for SSL server private key.
  or as a secret key for encrypting the passphrase, which you put
  into http.conf.

Use any service control program that can accept startup parameters
to start Orenosv service with master password.

Note that "NET START" cannot take startup parameters.  You have to
use OS-provided GUI service applet or other programs.  orenosv.exe also 
can be used as a service startup program.


  > orenosv -cu [service-name [parameter-1]]

e.g., > orenosv -cu orenosv my-master-password


When (re)starting Orenosv main server via Orenosv admin page, you do NOT 
have to give the same master password.  The admin server keeps it in its memory
so it can pass it down to the main process when starting it.

When (re)starting main server via admin page, you have an option to
change the master password.  The new password will be kept in admin processes
memory and will be used for subseqent startups of the main process.


As an alternative, you could also use the following parameter in admin.conf
(not http.conf)
Note that this will defeat the purpose of not storing the master password
in a file.

1) Put the master password in plain text:

  master_pwd = my-master-password

2) Store master password in a file and specify path to it in the following
   parameter:

  master_pwd_file = e:\mstrpwd.txt



IPv6 issues
===========
Follow simple instruction on admin/doc/ipv6.html.


- If you want to listen on a specific link-local IPv6 interface,
  append interface number to the link-local address as scope-ID.

  # in case of IPv6 link-local address, append interface number 
  # following '%'.
  http_listen = fe80::203:2fff:fe02:c640%3@8888
  #                                     ^^

You can find out the interface number by running "ipv6 if".


You may also have to specify an interface number when connecting
to a link-local address of the ftp server.  This is because 
sometimes the OS can't determine the correct interface number.

See this document for more info:
http://msdn.microsoft.com/library/default.asp?url=/library/en-us/winsock/winsock/link_local_and_site_local_addresses_2.asp



HTML Files Application
======================




EOF