hserv 16.0 documentation

 

Introduction

1
 
  hserv is a HTTP 1.1 conditionally compliant server.

hserv is very configurable and funny.

The main features are:

  • Run alone or as inetd service in multiple instance listening on different ports;
  • Accepts GET, HEAD and POST methods;
  • Basic file resuming;
  • Persistent connections;
  • Virtual hosts implemented;
  • If-Modified-Since supported, with many date formats;
  • rfc 19452 Auth supports;
  • Rejected-ips;
  • Mime types read from file, so you can had your mime;
  • Text parsing;
  • In line ARexx functions in html documents;
  • ARexx, REBOL, perl and exe cgi;
  • May be set to require ident service running at client host;
  • RxMUI powered.
    •      		 

     

    Author

    2
     
      I am Alfonso Ranieri .

    My e-mail address is alforan@tin.i.t

    My home page is at http://web.tiscalinet.it/amiga/

    		  

     

    Distribution

    3
     
     

    hserv is under the

    Warning

    4
     
     
    THIS SOFTWARE AND INFORMATION ARE PROVIDED AS IS. ALL USE IS AT YOUR OWN RISK, AND NO LIABILITY OR RESPONSIBILITY IS ASSUMED. NO WARRANTIES ARE MADE.
    		 

     

     

    Requirements

    5
     
      hserv needs:
  • AmigaOS 3.0 or higher
  • Miami or AmiTCP/Genesis - hserv DOESN'T work with TermiteTCP
  • rxsocket.library
  • rmh.library
  • rxasl.library
  • rxmui.library

    •  

    Installation

    6
     
      First of all run the installation script.

    Let's suppose you installed hserv in PATH: (complete path to a drawer).

    Follow this basic installation:

  • To install hserv as an inetd service:
  • If running on AmiTCP
  • open AmiTCP:db/services and (if not already present)
    add the line:
    http 80/TCP
  • open AmiTCP:db/inetd.conf and add the line:
    http stream TCP nowait root C:rxs rxs PATH:hserv.rexx
    •
  • If running on Miami
  • open Miami/Database/services window
    press "Add" gadget
    (if not already present) add the entry:
    Name: http
    ID: 80
    Protocol: TCP
  • open Miami/Database/Inetd window
    press "Add" gadget
    add the entry:
    Service: http
    Socket: stream
    Protocol: TCP
    Wait: nowait
    User: root
    Server: c:rxs
    Name: rxs
    Args: PATH:hserv.rexx
  • To install it as stand alone:
    run >NIL: <NIL: rx PATH:hserv
    (or just rx PATH:hserv)
    •

    Check if you have a services in inetd listening on 80/TCP
    or hserv will fail with can't bind socket error.

    		  

     

    Configuration

    7
     
      Configuration options are read from a file, which is the first argument of hserv .

    If file is omitted, hserv tries to open conf/hserv.conf

    Each line of the configuration file is in the form:

    <option> <value>

    There are ignored during parsing:

    • empty lines
    • lines beginning with # or ;
    • lines after the 1024th
    • chars after the 256th

    Words can be separated by space(s) and tab(s).

    The options are:

  • HostName - the host name, if none given, hserv tries to obtain it from the socket name.
    Don't set it if you don't know what you are doing.
    Default: none
  • Port - the TCP port to use (of course, only valid if running as stand alone, otherwise the port is set in services database)
    Default: 80
  • Admin - any occurrence of <!admin> in a text is converted to
    <A HREF="mailto:admin>admin</A>
    Default: none
  • Status - status of the server
    value are OPENED PAUSED
    Default: OPENED
  • DocumentDir - the dir where documents are
    Default: none
  • CgiDir - the directory where CGI macros are. It is used if and only if a "/cgi-bin/<file>" is received.
    Default: none
  • DocumentIndex - any request with a null file name is replaced with this default index.html .
    Default: none
  • Timeout - timeout in seconds for the receive request and send phase.
    Default: 300
  • KeepAlive - number of persistent connections for one istance of hs.
    Default: 4
  • SendDelta - the size of data in tcp send transactions.
    Default: 512
  • Auth - the auth file.
    Default: none
  • RejectedIP - the rejected ips.
    Default: none
  • Mime - the mime file.
    Default: none
  • Specials - the specials file.
    Default: none
  • Handlers - the handlers file.
    Default: none
  • VirtualHosts - the virtual hosts file.
    Default: none
  • Errors - special errors file.
    Default: none
  • Referers - special referers file.
    Default: none
  • PearlPath - complete path to perl, if you have it.
    Default: none
  • RebolPath - complete path to Rebol, if you have it.
    Default: none
  • TransferLog - a flag that indicates if requests must be logged.
    Values are ON OFF SYS
    Default: OFF
  • TransferFile - if TransferLog is ON, log requests in this file.
    Default: none
  • ErrorLog - a flag that indicates if errors must be logged.
    Values are ON OFF SYS
    Default: SYS
  • ErrorFile - if ErrorLog is ON, log error in this file.
    Default: none
  • HostNameLookups - a flags that indicates if the server should do a GetHostByName() on the client ip.
    Values are ON OFF
    Default: OFF
  • Ident - a flag that indicates if the client must have the ident service running; the server will connect it and get client ident.
    Values are ON OFF
    Default: OFF
  • OnlyAmigaClient - only Amiga client accepted; clients without the word "Amiga" in User-Agent field are rejected.
    Values are ON OFF
    Default: OFF
  • DefImage - sends images/def.image on errors.
    Values are ON OFF
    Default:ON
    •      		 

     

    Text parsing

    8
     
      Any time a file of mime <text/*> is encountered, the server makes this parsing on its' LINES:
  • changes the string <!ip> with the peer name
  • changes the string <!user> with the user name, if ident is ON, or unknown if ident is OFF
  • changes the string <!userat> with user@ip, if ident is ON, or ip if ident is OFF
  • changes the string <!admin> with the string
    <A HREF="mailto:admin>admin</A>
  • changes the string <!power> with the string
    Powered with RxSocket!
  • changes the string <!ver> with the string 15.0
  • changes the string <!this> with the current file name
  • changes the string <!InetDate> with the current date in GMT Internet format
  • changes the string <!include filename> and <!--#INCLUDE FILE="filename") with the content of filename. Due ARexx strings size limitation filename size must be less then 65536 characters
  • changes the string <!REXX fun> with the output of the function fun, an ARexx function called on the fly
  • changes the string <!CGI fun> with the result of the file created by the CGI fun with the first 2 lines discarded

    • The parsing is made for all but !CGI then for !CGI, but never recursively for !CGI.

    		  

     

    CGI

    9
     
      The term CGI refers to:
  • ARexx macros
  • perl macros
  • REBOL script
  • AmigaOS exe
    •

    The type of the macro is parsed from its file name extension:

  • ARexx macros must have the extension rexx
  • perl CGI macros must have the extension cgi
  • REBOL script must have the extension r
  • AmigaOS execs must have no extension

    • You can overwrite the type of a macro, specifying a line in Handlers

    A CGI macro of type perl will work if and only if you have defined PERLPATH

    A CGI macro of type REBOL will work if and only if you defined REBOLPATH

    An exe macro can be an AmigaDOS script with the s bit set .

    The directory CGIDir contains all the macro that are called in the form /cgi-bin/macro. It is a default directory for general porpouse macros.

    CGI are called with the same arguments in the request.

    They must write to stdout:

  • first line: "Content-Type:" mime
  • second line: (empty)
  • rest: data (mime specific)

    • Macros have their real directory as CurrentDir.

    If they are called from a <!CGI fun> the first 2 lines are discarded and the rest is inserted.

    ONLY file with mime text/* are parsed.

    		  

     

    RunTime

    10
     
      hserv has a standard AmigaDOS template:

    FILE,PORT/N,NOGUI/K,QUIET/K,START/K

  • FILE is the configuration file
  • PORT is the port to listen to it only works if hserv is started as a stand alone service it can be 0 < port < 65535
  • if it is not given, it is read from the config file
  • if the config file has no PORT options it is set to 80 by default
  • if port is 0, the port is searched in the services database
  • NOGUI don't open the window
  • QUIET don't log open/close to SysLog
  • START start asap
    •

    If the server runs as stand alone:

  • hserv opens an ARexx port;
  • this port accepts the commands:
  • QUIT quit the server
  • SHOW open the window
  • HIDE close the window
    •

    • If the config file is modified, the server auto reloads it.

    hserv does these controls before sending a file:

  • good request
  • peer info
  • Ident
  • OnlyAmigaClient
  • k-lined ip
  • file contains "//" or ":"
  • file exists
  • Auth
  • good request method
    		•  

     

    Bugs

    11
     
     
  • No way to pass cgi macros local vars, like the ip of the client, the arguments of a get or a post and so on, e.g. like Apache does
    		•  

     

    GUI

    12
     
      hserv comes with a full functional GUI

    The GUi is very easy to use, so there is not so much to say.

    		  

     

    Auth

    7.1

     
      The Auth file consists of lines in the form:

    <pattern> <realm> <login> <pass>

  • pattern is an AmigaDOS pattern, that will be applied to the complete file name requested.
  • realm is a symbolic name for the protected space the file(s) belongs to
  • login is the login
  • pass is the password

    • Due ARexx string-size limitation I set the max length of login:pass to max 120 chars.

    Anytime a file is requested, after it was parsed in a complete path to a file, and matches a pattern in a line of Auth file, an authentication request is send to the client.

    Try to join The Secret Garden

    you'll need to login with l:secret p:garden

    		  

     

    RejectedIP

    7.2

     
      The RejectedIP file consists of lines in the form:

    {IP} <pattern> <reason>

  • pattern is an AmigaDOS pattern, that will be applied to the ip of the client. If prefixed with IP, it is considered to be dotted , e.g. 194.2.3.*, otherwise it is a string. If HostnameLookups is not set, only dotted pattern are filtered.
  • reason is the reason for the k-line . It is send to the client

    • If pattern matches the ip, the connection is not accepted.

    If a non empty Rejectedip file is given, HostNameLookups is set.

    		  

     

    Mime

    7.3

     
      The Mime file consists of lines in the form:

    <mime> <ext> {SP ext}

  • mime is a mime type, e.g. <text/html>
  • ext is the extension of the file

    • Any file with an extension present in the left part of a mime line is considered to be of that mime.

    Default mime is <text/html>.

    		  

     

    Specials

    7.4

     
      The Specials file consists of lines in the form:

    <pattern> <code> <file> [args]

  • pattern is an AmigaDOS pattern, that will be applied to the complete file name requested.
  • code is on of:
  • CODE - http error code, a http head is created and sent back with code "file" (must be integer) without any further action - args is discarded
  • CALL - file is called and the current socket is passed to it ala inedt
  • file it depends on code value
  • args arguments for CALL

    • An examples is

    #?/documentation.html CODE 301 Location: http://localhost/doc.html

    that redirects documentation.html to the specified url.

    		  

     

    Handlers

    7.5

     
      The Handlers file consists of lines in the form:

    <pattern> <handler>

  • pattern is an AmigaDOS pattern, that will be applied to the complete file name requested
  • handler is one of
  • REXX ARexx macro
  • REBOL rebol script
  • CGI perl cgi
  • EXE executable
  • SEND send the file

    • If pattern matches the file name, the file is considered to be of one of the above type.

    E.g. a line like

    /CGI-BIN/counter REXX

    will make hserv call the macro counter as it was a REXX macro rather than an EXE macro .

    		  

     

    VirtualHosts

    7.6

     
      hserv implementation of virtual host is really simple and not even so much tested.

    The VirualHosts file consists of lines in the form:

    <hostname> <DocumentDir> [DocumentIndex]

    On connection, the VirtualHosts file is opened and if the host name of the request is found in a line, than the DocumentDir, DocumentIndex is specified, is used; if the host name is not found, the default DocumentDir is used.

    It also means, that for each virtual host the default configuration is used, only the DocumentDir and DocumentIndex can be changed.

    To test virtual hosts, add in the host database of the stack you

    are using, an entry like

    127.0.0.1 www.alfie.org

    Add in the VirtualHosts file a line like

    www.alfie.org <path-to-somewhere>

    and try to connect http://www.alfie.org with your browser.

    		  

     

    Errors

    7.7

     
      The Errors file consists of lines in the form:

    <httpCode/N> <macro> [newHttpCode]

    If a http code httpCode is going to be returned by hserv, e.g. the requested document was not found and so hserv is going to returns code 404, the Errors file is opened to find a line with that code.

    If the code is found, the macro specified is called as a cgi (but the macro must be specified with complete path, and doesn't have to be in the cgi-dir) and the output of the macro is sent, with the original code, if no newHttpCode is specified, or with newHttpCode if present.

    This is useful to overwrite standard hserv answers.