Access Server User/Group properties
-----------------------------------

A user_compile record is a record that contains at least some information
that must be processed when the AS iptables service restarts (such as
access control rules).

A user_connect record is record where all information in the record can be
assimilated at user connection time.

The significance of the difference between these two record types is that
user_connect records can be freely modified without restarting any
AS components, while user_compile records, if modified, require
that the iptables service component of the Access Server be restarted
via the "./sacli start" command.

All records should have a 'type' key indicating one of the four record
types:

1. user_default -- __DEFAULT__ record
2. user_compile -- user record queried on iptables compile or user connect
3. user_connect -- user record queried on user connect only
4. user_connect_hidden -- like user_connect, but hidden from Admin UI
5. group -- group record

Userprop key prefix naming convention:
  pvt_x -- non-inheritable, allowed in user_connect or user_compile records
  conn_x -- non-inheritable, allowed in user_connect records only
  prop_x -- inheritable, allowed in user_connect or user_compile records
  cli_x -- inheritable, allowed in user_connect or user_compile records,
           interpreted at profile-build time
  def_x -- inheritable only from __DEFAULT__ and for users not present in
           userprop DB -- will be renamed to prop_x
  other -- interpreted at iptables compile time

user_connect records are only accessed at connect time.  user_compile
records are accessed at iptables compile time and connect time.

Userprop keys interpreted at iptables connect time:

  prop_superuser (boolean) -- designate as admin (also used at iptables compile time if true)

  prop_autologin (boolean) -- allow autologin

  prop_deny (boolean) -- deny access

  prop_deny_web (boolean) -- deny access to CWS and XML/REST web services

  prop_lzo (boolean) -- enable lzo compression

  prop_autogenerate (boolean) -- auto generate certificate on first CWS access

  prop_reroute_gw_override (string)
    'disable'  -- disable reroute_gw for this client
    'dns_only' -- disable reroute_gw for this client, but still route DNS
    'global'   -- use global reroute_gw setting (default)

  pvt_password_digest (string) -- sha256 password hash when local auth is enabled.

Group userprop keys interpreted at connect time:

  These properties can only be specified for connect-time userprop
  records, i.e. records that don't have any iptables compile-time keys.

  conn_group -- (string) designate this user as being a member of the
                given group

  conn_impgrp -- (bool) no group is specified, but select the group
                 based on which one owns the static IP (conn_ip).

  conn_ip -- (string: IP address) dynamic IP address that should be
             assigned to user; if group is not specified, AS will
             try to derive the group by looking up this IP in
             group_subnets (only in Layer 3 mode)

Userprop keys interpreted at both compile and connect time:

  inherit -- (list of strings) a list of groups/users that this
             group/user will inherit from

  prop_superuser (boolean, only used if true) -- designate as admin (also used at
                                                 iptables compile time if true)

Userprop keys interpreted at iptables compile time (only in Layer 3 mode):

  conn_ip (string) -- static IP address

  c2s_route (list of subnets) -- These subnets may route through a VPN
      client acting as a gateway:
          c2s_route.0    <network>/<numbits>
          c2s_route.1    <network>/<numbits>

  access_from/access_to -- Allow user/group (or subnets routing through a
      VPN gateway authenticated as this user) to access these resources:
          access_from.0 <resource1>
          access_from.1 <resource2>
          ...

      Allow these resources to access user IP (or subnets routing
      through a VPN gateway authenticated as this user)
          access_to.0 <resource1>
          access_to.1 <resource2>
          ...

      A resource begins with '+' (allow) or '-' (deny), then
      continues with a type tag (such as 'USER', 'SUBNET', etc.)
      If the type requires additional parameters, the type tag is
      followed by a colon (':'), and type-specific data:
      
      1. USER:<a user or group name>[:SERVICES]
      2. SUBNET:<network>/<numbits>[:SERVICES]
      3. ALL               -- matches everything, i.e. 0.0.0.0/0
      4. ALL_VPN_CLIENTS   -- matches all IP addresses and subnets
                              owned by all VPN clients
      5. ALL_S2C_SUBNETS   -- matches all server-side subnets as defined
                              by vpn.server.routing.private_network

      The optional SERVICES parameter is a comma-separated list
      of protocol/port values or well-known service names, e.g.:

        +SUBNET:10.10.0.0/24:https,udp/1194,tcp/1194

      This example allows access to/from the network 10.10.0.0/24,
      but only https (TCP 443), UDP 1194, and TCP 1194 traffic
      is allowed.

      The currently list of well-known service names include:

      {
        'ftp'   : (('tcp', 21),),
        'ssh'   : (('tcp', 22),),
        'smtp'  : (('tcp', 25),),
        'http'  : (('tcp', 80),),
        'pop3'  : (('tcp', 110),),
        'https' : (('tcp', 443),),
        'imaps' : (('tcp', 993),),
        'rdp'   : (('tcp', 3389),),
      }

  dmz_ip (list of strings) -- Implemented per-user DMZ IP addresses.
    This feature allows one or more public IP addresses (and optionally
    a specific protocol and port number for each IP address) to be NATed
    at the server into the VPN tunnel and then routed to a specific
    client.

      dmz_ip.0 : IPAddr[:'tcp'|'udp'/port]
      dmz_ip.1 : IPAddr[:'tcp'|'udp'/port]
      ...

  bypass_route (list of subnets) -- These subnets or DNS names will
      NOT be routed through the VPN.
          bypass_route.0    <network>[/<numbits>]|DNS_NAME
          bypass_route.1    <network>[/<numbits>]|DNS_NAME
	  ...

      If numbits is omitted, it defaults to 32.

      For example:

        "bypass_route.0": "10.10.0.0/24",
        "bypass_route.1": "1.2.3.4",
        "bypass_route.2": "google.com",


Group userprop keys interpreted at iptables compile time (except for
group_declare, all others only defined for Layer 3 mode):

  group_declare -- (bool) declare that a 'user' in userprop should
                   really be considered a group.

  access_from (list of strings) -- same as for users

  access_to (list of strings) -- same as for users

  group_subnets -- (list of subnets) a list of subnets that are owned
                   by the group

  group_dynamic_range -- (an IP range) range of IP addresses within
                         one of the group_subnets to use for dynamic
                         IP address allocation for this group

Group config keys (only in Layer 3 mode):

  vpn.server.group_pool.<n> -- (list of subnets) a list of subnets
                           that will be partitioned across groups
                           that request it via group_pool userprop key

Client profile keys:

  cli_service (bool) -- if true, the client profile should run as a
                        service

  cli_pref_managed (bool) -- if true, the client installer will default to
                             cli_pref_user_may_import_unsigned_profile=False
			     and cli_pref_user_hostspec="", i.e. non-admin
			     users will not be able to use the universal
			     client feature or import unsigned profiles

Setting client default global properties:

When a profile is bound to a client installer, the installer will allow the
profile to specify initial global properties.  For each global property
specified as settings_info in clisettings.py, the property can be referred
to as a user property by prepending a "cli_pref_" prefix.

For example, the "exec_script" client property can be encoded in
server-side user properties as "cli_pref_exec_script".

Each of these properties is described in detail in cliapixml.py
(the properties are described under the xmlrpc_SetPreferences method
without the "cli_pref_" prefix).

Userprop script keys:

 * environmental variables to be set before script executes:

     prop_cli.script_env.<linux|win|mac|all>.KEY : VALUE

   Special environmental variables that may be set on the AS:

   PREPATH -- if defined, will be prepending to client's PATH before the
              script is executed.

   Special environmental variables set by the client backend before
   scripts are executed:

   N_RECONNECTS (integer rendered as string) -- the number of reconnects
                that have occurred thus far in this session.

   GRACEFUL_DISCONNECT ("0" or "1") -- set to "1" if this disconnect was
                       requested by the user, and "0" if the disconnect
                       was unexpected.

 * script content:

     prop_cli.script.<linux|win|mac|all>.<user|admin>.<connect|disconnect>
     (multi-line string) -- script content

Script shebang usage for Windows (on unix, shebangs are processed by the OS):

  Leading comment prefix can be one of:
  1. #
  2. '
  3. //
  4. REM
  5. rem

  In the examples below, '#' is used as the comment prefix,
  but it can be replaced with any of the above prefixes.

  [script content] -- defaults to cmd.exe processing

  #!foo.exe
  [script content... -- find foo.exe in path]

  #!foo.exe -a somearg
  [script content... -- pass options (the last option is the implicit script filename)]

  #!"c:\Program Files\Foo Corp\foo.exe" -a somearg
  [script content... -- quote the program exe]

  #!foo.exe
  #EXT foo
  [script content... -- script will be written to a .foo file before execution]

  #PYTHON
  [python code -- execute python script using OpenVPN Client built-in python interpreter]

  #!/usr/bin/env python
  [python code -- execute python script using OpenVPN Client built-in python interpreter
                  on Windows, and using default python install on unix.]
