Here's a run through of all the settings for cardservproxy 0.8.9, roughly in the order that they appear in the example proxy-full.xml.

An element path such as "connection-manager/service-map/mapper/reset-services" means the following element in proxy.xml:

<cardserv-proxy><connection-manager><service-map><mapper>
<reset-services/>
</mapper></service-map></connection-manager></cardserv-proxy>

Attributes marked with * are mandatory.

Glossary:
- DVB: Digital video broadcasting, http://en.wikipedia.org/wiki/DVB
- CA (DVB-CA, EMM, ECM) : Conditional Access, http://en.wikipedia.org/wiki/Transport_stream
- TS: Transport stream, http://en.wikipedia.org/wiki/DVB
- CWS: Codeword server, aka cardserver. The server application (e.g newcs) that accept client connections and manages card communication.
- Service: DVB-service, typically tv or radio channel (but can also be data containing software or just about anything). Identified by a numerical id refered to as the sid.
- newcamd/radegast: Communication protocols (tcp) encapsulating the DVB-CA traffic for use over ip networks. Named after the applications that introduced them.
- Profile: A proxy concept for keeping multiple card and client types separate without understanding the contents of the CA traffic. Typically corresponding to one provider/vendor. Within a profile there can only be one CA system, and all incoming messages to the profile listen port are assumed to belong to this system. A profile is essentially a virtual cardserver with a potentially infinite capacity card.

Contents:


cardserv-proxy (attributes: *ver)

The root element for the proxy config file.

- ver: The version attribute must always match the version of the proxy itself (lib/cardservproxy.jar). This is an intentional safeguard to force a manual check of the proxy.xml contents when upgrading to a new version. Even if no changes are strictly required from one particular version to the next, it makes sense to double-check. To get a fresh start that is guaranteed to work with the currently installed version, simply remove proxy.xml entirely and start without it. A blank template will then be generated.

Example: <cardserv-proxy ver="0.8.4">
ca-profiles

A profile in the proxy corresponds to one type of card or provider/vendor. Each connected CWS and client will need to be assigned to one profile. The proxy opens listening-ports for each profile so clients are assigned profiles by the port(s) they connect to. CWS connectors are assigned either by manually configuring them to a specific profile, or by auto-assignment based on the ca-id of the card data thats returned on login (auto-assignment only works for newcamd CWS).
Cards within a profile typically need to be identical. For some ca-systems, multiple cards cannot be placed within the same profile even though they appear to decode the same services on their own. Provider idents etc typically need to match. If they don't, the proxy will disable the card that differs and log warnings (this check can be overriden however).
ca-profiles/default-des-key

The default des key for all incoming newcamd connections. Clients will need to match this.

Example: <default-des-key>01 02 03 04 05 06 07 08 09 10 11 12 13 14</default-des-key>
ca-profiles/max-threads

Maximum number of java threads the proxy will allow to be spawned (default: 1000). This is a global limit affecting all profiles and connectors. Each ca profile, connected client session and cws connector requires at least 1 thread each. If the limit is exceeded, no new connections will be accepted until the total thread count drops again. Most JVM's will experience problems once the count reaches somewhere between 2000 and 3000 threads, but significantly more (or less!) may be possible depending on os/hardware.
NOTE: If you do increase this, keep in mind that most OS'es have a limit on the number of open file handles (and each socket counts as a file). On most *nix variants you can use ulimit -n and the lsof util (list open files) to find such limits, but the methods for increasing them vary.

Example: <max-threads>1500</max-threads>
ca-profiles/session-timeout

Maximum idle time for client sessions, in minutes (default: 120). Sets how long the proxy will keep blocking reads open, for the tcp connections from clients. The reason for the very high default is to reduce the frequency of reconnects from clients in standby mode that do not send keep-alives. In large shares it may make sense to decrease this limit significantly, so resources aren't wasted on connections that may have died hours ago.

Example: <session-timeout>240</session-timeout>
ca-profiles/session-keepalive (attributes: exclude-clients)

Send newcamd keep-alive messages to any session that is idle longer than this many minutes (default: 0 = off). Normally only newcamd clients send these to servers, but since most clients seem to ignore the message it is possible to use to find dead sessions faster (useful in very large shares, since the session-timeout can be lowered and resources reclaimed). NOTE: if clients are already sending keep-alives on their own (like most should, by default), make sure your interval is greater than that of the client so messages wont be sent when there's no need. FINE log-level can be used to see keep-alive traffic.

If a session-keepalive is set but is higher than session-timeout, timeouts will trigger a keep-alive send (if the client isn't excluded) instead of a disconnect.

- excluded-clients: List of client names/ids that wont be sent keep-alives (separated by space, default: "" = send to all). Since its undefined what clients do when they receive a keep-alive, some may not handle it well (or fail altogether if they get any). If you find one, list it here. A client that actually responds to the keep-alives could potentially cause a loop, so use with care.

Example: <session-keepalive exclude-clients="someclient otherclient thirdclient">10</session-keepalive>
ca-profiles/newcamd-maxmsgsize

The global maximum size for newcamd messages (default: 400). This corresponds to CWS_NETMSGSIZE in the native clients/servers, and was previously always 240. Increasing the limit shouldn't affect anything unless any large messages are actually received, but just in case the value can now be configured.

Example: <newcamd-maxmsgsize>480</newcamd-maxmsgsize>
ca-profiles/profile (attributes: *name, ca-id, enabled, debug, cache-only)

One profile definition.
- name: Typically the provider name but can be any short string (case sensetive, may not contain spaces).
- ca-id: Assigns a ca-id to the profile. What this is used for depends on the protocol (it is required if the profile has radegast listeners defined, or is cache-only). Set it to 0000 to indicate that ca-id doesn't matter (i.e is determined by the newcamd card-data that the card-connectors will receive on login).
NOTE: If you do set an id (that isn't 0000) it has to match the ca-id of the newcamd cards exactly, or they will be automatically disabled on connect (see cws-connectors for more details).
- enabled: true/false (default: true) Allows for temporarily disabling one profile. Doing so will close all its listening ports, and will generate errors if there are active connectors that reference the profile in question (disable all the connectors first).
- debug: true/false (default: true) Controls whether a backlog of 100 ecm transactions should be stored for each user session for troubleshooting purposes (accesible via http @ /xmlHandler?command=user-log&name=user). NOTE: Under most circumstances it makes sense to always keep this switched on, but for very large shares it can consume considerable amounts of memory (hundreds of megs).
- cache-only: true/false (default: false) Switches the profile to only use cached cw's, never forwarding anything to card connectors (no connectors need to be defined when this is set). See 0.7.2 changelog for details.

Example: <profile name="cable" ca-id="0B00" enabled="true" debug="true">

ca-profiles/profile/newcamd (attributes: *listen-port, bind-ip)

Defines a newcamd listener for the profile.
- listen-port: TCP port number.
- bind-ip: Optional local IP to bind the listener to (default: all - 0.0.0.0).

Example: <newcamd listen-port="13112" bind-ip="192.168.0.23"/>

ca-profiles/profile/newcamd/des-key

Overrides the default-des-key for a particular newcamd listener.

Example: <des-key>14 13 12 11 10 09 08 07 06 05 04 03 02 01</des-key>

ca-profiles/profile/newcamd/card-data (attributes: *type, name, override-au)

Allows specifying the card-data given to clients that connect to this newcamd port (in response to MSG_CARD_DATA_REQ, see protocol.txt). Only use this if you know you need it. If this element is omitted, the proxy will return data from the least loaded card in the profile.
- type: Set to either connector, file or empty. If set to empty, the name attribute is ignored and dummy data with only the ca-id for the profile is returned (and a single 000000 provider ident).
- name: If type is connector then name should be a connector name. If type is file then name is path and filename to read the card-data from.
- override-au: true/false (default: false). Set to true and the specified card-data will be given even to au-users (who would normally get data from the cards they update).

Example: <card-data type="connector" name="card1"/>

ca-profiles/profile/newcamd/no-encryption

true/false (default: false) Set to true and the proxy will assume newcamd traffic to this listen port is unencrypted and use it as is. The only client that supports this is the alex-cs hardware.
ca-profiles/profile/radegast (attributes: *listen-port, bind-ip, sid-in-0x21)

Defines a radegast listener for the profile. If a profile has a radegast listener defined then ca-id must be set. As there is no user auth, only the ip allow/deny lists control access to radegast listeners.
- listen-port: TCP port number.
- bind-ip: Optional local IP to bind the listener to (default: all - 0.0.0.0).
- sid-in-0x21: true/false (default: true). Determines whether to attempt to parse radegast field 0x21 as the sid. Only switch this off if you notice that it yields incorrect sids.

Example: <radegast listen-port="13115" sid-in-0x21="true"><allow-list>192.168.0.*</allow-list></radegast>

ca-profiles/profile/[newcamd|radegast]/allow-list

Optional ip white list
A list of ip masks (wildcards supported) separated by space. If this is set, only matching source addresses will be able to connect.

Example: <allow-list>192.168.0.* 10.0.*</allow-list>

ca-profiles/profile/[newcamd|radegast]/deny-list

Optional ip black list
A list of ip masks (wildcards supported) separated by space. Allows blocking connections based on source ip (checked after the allow-list).

Example: <deny-list>192.168.0.116 10.0.0.7</deny-list>

ca-profiles/profile/services-file (attributes: format, provider)

Path and filename for an enigma1 services file (result of service scanning on a dreambox, usually it is /var/tuxbox/config/enigma/services in case of an enigma1 box, and /etc/enigma2/lamedb for engima2). The services file is used by the proxy exclusively to assign readable names to services, for logging and remote monitoring.

- format: Optional, format of the services file (defaults to enigma). Supported formats are "enigma" (enigma1/2 has the same one), and "simple". Simple assumes a plain text file with: sid=service name (one per line, sid in hex, names in ISO-8859-1). This is just a fallback in case no live data can be obtained, the idea is to _avoid_ manually specifying service names by instead importing it from the metadata of any existing dvb-solution (or even directly from the transport stream).
- provider: Optional and only applicable for enigma format. This is a filter, telling the proxy that only service definitions matching this provider name should be parsed for this profile. For dvb-c/t the services file typically contains only services for one provider, so this attribute can be omitted (i.e. everything in the file is relevant for this profile).

For dvb-s it can contain multiple providers, so check the contents of the file and set a provider name that matches the card(s) that will be in this profile.
The provider name will appear for each service in the file, with a line like:
p: providername
If services appear in the file with several different provider names even though they are available on the same card, or if some services have p: unknown, then multiple provider names can be specified (separated by space). Multiple profiles can point to the same services-file, with different providers set.
Once a services file has been successfully loaded, the proxy will monitor that file for changes and automatically reload it if any are detected (allowing for automated file updates).

Example: <services-file provider="unknown someprovider multiple strings">etc/services</services-file>
Example: <services-file format="simple">etc/servicesForProfileX.properties</services-file>
ca-profiles/profile/max-cw-wait

This defines the maximum wait time (in seconds) for anything trying to get a CW reply from this profile, before aborting with a timeout (flag T). Under normal circumstances this should be set to the maximum time a client can wait for CW reply without experiencing a freeze (or 1 second above that). Applies to all CWS connectors in this profile, if set here it overrides the global setting in connection-manager.
To determine a reasonable value for max-cw-wait, it is possible to use the test-delay feature in the LoggingPlugin. This can insert an artificial delay into the processing of requests for a specific test-user (source ip address). Increase the delay gradually until freezes occur for the test-user and note the total ecm time in the client logs when this happens, this is your max-cw-wait. Make sure the client ecm timeout is set high enough not to interfere with the result.
See README.Optimization.txt for more details.
ca-profiles/profile/congestion-limit

The maximum estimated queue time on a connector before the proxy considers it to be congested, and tries to avoid using it (by instead using connectors that would normally be excluded due to a higher metric number). Value in seconds, must be between max-cw-wait/2 and max-cw-wait. Use with care, and primarily if you have many connectors with differing metric priority set. Applies to all CWS connectors in this profile, if set here it overrides the global setting in connection-manager.
logging (attributes: log-ecm, log-emm, log-zapping, hide-ip-addresses)

Main log configuration for the proxy. File logging only.
- log-ecm: true/false (default: true). Set to false to disable the INFO level ECM logging.
- log-emm: true/false (default: true). Set to false to disable the INFO level EMM logging.
- log-zapping: true/false (default: true). Set to false to disable the INFO level logging when users switch service.
- hide-ip-addresses: true/false (default: false). Set to true to mask any ip addresses (xxx.xxx.xxx.123) or hostnames (host.xxx.xxx) logged for the normal INFO level non-debug output. This does not apply to web access logs or logging filters.

Example: <logging log-ecm="false" log-emm="false" log-zapping="false" hide-ip-addresses="true">

logging/log-file (attributes: rotate-count, rotate-max-size)

Main log file.
- rotate-max-size: 1 or more to enable, value in kb (default: 0 = off). The maximum size the log file is allowed to reach, before rotating (moving on to the next file, or overwriting if count is set to 1).
- rotate-count: 1 or more to enable (default: 0 = off). The number of log files to cycle through when max-size is reached. File names will be suffixed with .0, .1, .2 and so on. The file currently in use will have an additional corresponding .lck file.

Example: <log-file rotate-count="5" rotate-max-size="1024">log/cardserv.log</log-file>

logging/log-level

The log level determines the verbosity. Supported levels are:
OFF - no logging
SEVERE - only errors that should normally not occur
WARNING - warnings and common errors only
INFO - default level, includes all ECM/EMM's unless disabled by log-ecm/log-emm attributes.
FINE - includes some cache events, remote api access and similar
FINER - all cache events, some net traffic events
FINEST - all net traffic/encryption related events
ALL - everything, same as FINEST

Example: <log-level>WARNING</log-level>

logging/silent

true/false (default: false). Controls logging to system out (in addition to log file). Set to true for log file only.
logging/debug

true/false (default: false). Controls logging of line numbers, thread names and full stacktraces.
logging/warning-threshold (attributes: *bad-flags, *max-delay)

Determines which user transactions to consider as potential problems (to be included for the user-warning-log http query). These events are only recorded if the profile has debug set to to true.
See README.Optimization.txt for more hints on how to interpret transaction flags.

- bad-flags: List of all flags that should be considered harmful (as a single string, no separators).
- max-delay: In milliseconds, any transaction exceeding this limit will be considered a problem and traced (default: 5000).

Example: <warning-threshold bad-flags="YTSGXWD-" max-delay="7000"/>

logging/event-threshold (attributes: *min-count)

Allows hiding errors on the status web, unless they occur repeatedly. Useful in large shares (many cards) that are set up so a single timeout doesn't really affect users.

- min-count: The number of failures required (in a row) to generate a CWS event on the status web (default: 1).

Example: <event-threshold min-count="2"/>

rmi (attributes: enabled)

Settings for the remote api (java remote method invocation). This allows other java applications a full interface for remote control and status overview. See test/RemoteTestClient.java in the source for an example.
- enabled: true/false (default: false)
rmi/allowed-ip-masks

RMI has zero security, anyone with access to the ports can use it. Use this to limit access to a list of trusted ip-masks. If allowed-ip-masks is omitted or left empty, the ports will still be open but terminating all connection attempts (note that internal local access for components such as the http/xml interface will still be possible). Masks are specified using standard glob format (? and * wildcards).

Example: <allowed-ip-masks>192.168.0.* 10.0.1.2</allowed-ip-masks>
rmi/registry-port

TCP port for the RMI registry (default: 4099).
rmi/local-port

TCP port for the proxy remote api object (default: 4098).
rmi/local-name

Name of the proxy remote api object within the registry (default: cardservproxy). A remote application would connect to the registry and perform a lookup for this name to gain access. Unless running multiple proxies in the same JVM, there should be no need to change this.
rmi/display-name

Name of this proxy instance, as shown to a connecting remote application. This is also the name returned by http/xml queries (e.g proxy-status).
rmi/status-web (attributes: enabled)

Controls the built in http interface. This is built on top of RMI and allows non-java remote applications a generic xml-based query interface. See README.HttpXmlApi.txt for full docs.

- enabled: true/false (default: false)
rmi/status-web/listen-port

TCP port for the built in httpd.
rmi/status-web/ssl (attributes: enabled)

Enable to use https instead of http.

- enabled: true/false (default: false)
rmi/status-web/ssl/keystore (attributes: *password)

If ssl is enabled, the proxy needs a certificate to present to connecting clients. This needs to be in a java keystore file, specified here. To create such a file, use the keytool that is included with the jre/j2sdk. The following syntax will generate a new keystore with a self-signed certificate for localhost (use the hostname or IP that your status-web will be accessed via) and a 1000 day validity:
keytool -keystore cs_keystore -genkey -alias Cardservproxy -keyalg RSA -storepass 123456 -keypass 123456 -dname "cn=localhost" -validity 1000
- password: The password for the keystore file (and the key password, both must use the same)

Example:
<ssl enabled="true">
<keystore password="123456">etc/cs_keystore</keystore>
</ssl>

rmi/status-web/war-file

In addition to the xml interface, the built in httpd can serve static content from a specified war file (web-archive, which is a standard zip file).

Example: <war-file>lib/cs-status.war</war-file>

rmi/status-web/welcome-file

A file within the war file to be shown to clients accessing "/" (default: cs-status.html). The path is relative to the root of the dir structure in the war file.

Example: <welcome-file>cs-status.html</welcome-file>
rmi/status-web/log-file (attributes: rotate-count, rotate-max-size)

Standard web-access log for the httpd, using apache combined format. Omit this to disable access logging.
- rotate-max-size: 1 or more to enable, value in kb (default: 0 = off). The maximum size the log file is allowed to reach, before rotating (moving on to the next file, or overwriting if count is set to 1).
- rotate-count: 1 or more to enable (default: 0 = off). The number of log files to cycle through when max-size is reached. File names will be suffixed with .0, .1, .2 and so on. The file currently in use will have an additional corresponding .lck file.

Example: <log-file>log/web-access.log</log-file>

user-manager (attributes: *class, allow-on-failure, log-failures)

Defines the user-manager for the proxy. This is used for authenticating all client access, via both the newcamd protocol and the http/xml interface.
- class: The java class name of the user manager implementation. This allows the entire user handling to be easily replaced, for example to use an existing remote database or passwd file of an arbitrary format/type (see README.XmlUserManager.txt for one example). The default built-in user manager reads the user definitions directly from the proxy.xml config file.
A user manager class must implement com.bowman.cardserv.interfaces.UserManager (or extend the default SimpleUserManager) and be accessible in the classpath.
- allow-on-failure: true/false (default: false). If a user-manager is unable to verify the identify of a user or complete a request for info due to internal/temporary problems (such as network issues in a remote usermanager), this controls if the manager automatically allows access for that user. I.e: disable security completely in case the user database is down.
- log-failures: true/false (default: false). Log login failures.

Example: <user-manager class="com.bowman.cardserv.MySqlUserManager" allow-on-failure="true" log-failures="true">
user-manager/auth-config

This is the arbitrary configuration that is presented to the user manager implementation, it can contain anything the user manager needs. For the built in SimpleUserManager it will contain the actual user definitions.
user-manager/auth-config/user (attributes: *name, *password, ip-mask, profiles, max-connections, admin, enabled)

One user definition for the SimpleUserManager (also used by the XmlUserManager, see README.XmlUserManager.txt for more details):
- name: User name, avoid long names, spaces and special characters. There are no particular limitations as far as the proxy is concerned, but the camd clients may have them.
- password: Avoid special characters.
- ip-mask: Only allow connections from a particular ip or ip range, for this user. This applies only to the newcamd protocol, not http/xml. Masks can use glob wildcards (? *).
- profiles: List of profiles that this user has access to, separated by space. If this is empty or omitted the user will have access to all defined profiles. NOTE: This is a performance safeguard, not an access control feature. It's there only to reduce the risk of users accidentally connecting to the wrong profile and poisoning the service mapper.
- max-connections: Number of connections to allow, if the user exceeds this then any older existing connections will be closed. If no max-connections value is specified, the user will be allowed one connection for each accessible profile.
- admin: true/false (default: false). Is this user an administrator? Affects access to http/xml api features only.
- enabled: true/false (default: true). Allows disabling of accounts without deleting them.
- map-exclude: true/false (default: false). Set to true to prevent the user from causing changes to the service maps. If a particular user is sending bad ecms or is otherwise misbehaving, this will protect the service mappings and ensure no other users are affected. Only use this if you are sure a particular client is misbehaving, the service mapping can't work if no clients are allowed to update the map.
- debug: true/false (default: false). Set to true to enable ecm/emm/zap logging for this user only (has no effect if these are already enabled globally).
connection-manager

This section deals with the connections to the CW servers, and everything related to that.
connection-manager/reconnect-interval

The interval between connection attempts (in seconds) for servers that are not are not connected. Applies to all CWS connectors. Minimum interval is 5 seconds (anything lower becomes 5).
connection-manager/max-cw-wait

If a CWS connection is congested or not responding, this defines the maximum wait time (in seconds, default: 9) for anything trying to get a CW reply, before aborting with a timeout (flag T). Under normal circumstances this should be set to the maximum time a client can wait for CW reply without experiencing a freeze (or 1 second above that). This is the default for all CWS connectors in all profiles.
To determine a reasonable value for max-cw-wait, it is possible to use the test-delay feature in the LoggingPlugin. This can insert an artificial delay into the processing of requests for a specific test-user (source ip address). Increase the delay gradually until freezes occur for the test-user and note the total ecm time in the client logs when this happens, this is your max-cw-wait. Make sure the client ecm timeout is set high enough not to interfere with the result.
See README.Optimization.txt for more details.
connection-manager/default-des-key

The des key the proxy will use when connecting to a newcamd CWS, if nothing else is specified for a particular connector.

Example: <default-des-key>01 02 03 04 05 06 07 08 09 10 11 12 13 14</default-des-key>

connection-manager/default-keepalive-interval

If a newcamd CWS connection is inactive longer than this period (in seconds) the proxy will send a keep alive msg.

connection-manager/default-client-id

The 2 bytes that identify a newcamd client on login (for newcs). Can be set to anything (as of 0.4.11). Use 00 00 or anything unknown to be identified as "generic". NOTE: avoid identifying as Mgcamd when connecting to newcs, as this will apparently cause newcs to switch to an incompatible variant of the protocol.

Example: <default-client-id>67 62</default-client-id> <!-- identify as Gbox2CS -->

connection-manager/default-max-queue

The maximum number of queued ecm requests that the proxy will allow to build up on one connector (default: 50). This is a safeguard limit to trap internal/os/network problems faster, if exceeded the proxy will assume something has gone wrong and disconnect the connector. The theoretical max queue that would make sense for a connector (assuming all reqs in the queue are unique) can be determined by: max-cw-wait / ideal-card-processing-time.

Example: <default-max-queue>60</default-max-queue>

connection-manager/default-min-delay

Delay in ms inserted between consecutive ecms to one connector in async mode (default: 10). A workaround for servers that misbehave when requests are too close together, for example because their cpu is maxed out (happens on slow platforms with some newcs versions, the server would respond with the same exact reply multiple times in a row with the real ones being lost).
This means the card will appear slightly slower, but hopefully more stable. Has no effect on connectors in synchronous mode.

Example: <default-min-delay>30</default-min-delay>

connection-manager/timeout-disconnect-threshold

The number of consecutive timeouts allowed to occur before a connector is closed and reconnect attempted (default: 2).
connection-manager/cannot-decode-wait

NOTE: This element is only applicable in custom setups with multiple proxies using ClusteredCache.

This allows you to set a configurable delay when service mapping and connection-manager determine that there are no cards available that can decode a given ecm (or there are no cards at all). Instead of immediately responding with a cannot-decode reply, the proxy will wait the specified number of seconds and then check the cache again.
This increases the chances of a cache hit through sharing. It will have no effect on cache-only profiles since these always wait as long as possible, but if you're using cache sharing in combination with local cards you should try this and set it to 1-4 seconds.
connection-manager/congestion-limit

The maximum estimated queue time on a connector before the proxy considers it to be congested, and tries to avoid using it (by instead using connectors that would normally be excluded due to a higher metric number). Value in seconds, must be between max-cw-wait/2 and max-cw-wait. Use with care, and primarily if you have many connectors with differing metric priority set.
connection-manager/hard-congestion-limit

true/false (default: true). If true, the proxy will block all forwards to congested connectors (or connectors in timeout states) until they are responding normally, even if there are no other alternatives available. The requests that would have been forwarded instead receive empty replies immediately (flag N), giving the client an opportunity for quick retries.
connection-manager/log-sid-mismatch

true/false (default: true). Log warnings if a server replies with a different sid compared to what was requested. This is usually a sign of errors that warrant further investigation, but could occur naturally (e.g when multiple services share the same ecm sequence). If you know it to be harmless, set this to false to disable the warnings.
connection-manager/delay-missing-sid

Delay in millisecs (default: 100). This adds a short delay for any incoming request without sid, before the cache is checked. The idea is to increase the likelyhood of a another request for the same ecm (but with sid specified) arriving first in the cache. This is to avoid having a large number of clients waiting in the cache for a forward that might get routed to the wrong card (because it had no sid). If you do have users that don't send sid, and this causes problems for them, just set it to 0.
connection-manager/service-map

The service mapper keeps track of which cards can decode which services, and tries to keep this information up to date with a minimum of probing/trial & error.
NOTE: See the end of README.txt for more information on service mapping.

connection-manager/service-map/mapper (attributes: enabled)

Default service mapper settings that apply to all profiles unless overridden.
- enabled: true/false (default: true). Disabling service mapping means the proxy will no longer keep track of which cards can decode which services, but instead assume all cards are identical (and to only apply load balancing when selecting a card). Setting this attribute here determines the default state for all profiles that don't specify anything else.
connection-manager/service-map/mapper/cache-dir

Where to store the service-map (default: cache, relative to the proxy start dir). Not to be confused by the real time cache thats maintained by the cache-handler (and only kept in memory). Delete the .dat files in this dir and restart to clear all proxy knowledge of services on the cards.
connection-manager/service-map/mapper/cache-save-age

Save the service-map to disk if it is older than this (age in seconds, default: 300). If no changes have occured it will not be saved.
connection-manager/service-map/mapper/auto-map-services

true/false (default: true). If the mapper receives an ECM for a service where it lacks status info (i.e it doesn't know where this service can be decoded), this controls whether it should try to find out right away by sending the ECM to all cards with unknown status. This should probably always be set to true.
connection-manager/service-map/mapper/reset-services

A list of service ids (hex integers, separated by space) that define services for which the proxy should not remember the state for each card. This can be PPV services or services with shared ids (i.e one service during day time and another at night). The service mapper will forget these services every hour, on the hour (as of 0.4.10).
It probably makes little sense to set this globally as service ids are likely to be profile-specific (see below for overrides per profile).

Example: <reset-services>51f 520 515</reset-services>

connection-manager/service-map/mapper/allow-services

A list of service ids (hex integers, separated by space). Inverse of block-services, only sids listed here will be forwarded to cards. If you know exactly which sids exist on the cards in the profile, use this to eliminate probing and also trap bad ecms (with bogus sids) before they get forwarded. I.e: Either set this to list all of the services the provider has, or don't use it at all (omit the element or keep it empty to disable the allow list).
It probably makes little sense to set this globally as service ids are likely to be profile-specific (see below for overrides per profile).
NOTE: this is a performance tweak, not an access control feature! Blocked sids can still be watched by all users if they appear in the cache. By design the proxy has no limitations on what users can access, everything is meant to be fully available to everyone.

Example: <allow-services>44f 43b 456 45f 421 452 44e 458 43d 45e 43c 3fd</allow-services>

connection-manager/service-map/mapper/block-services

A list of service ids (hex integers, separated by space), that are known not to exist on any connected cards. Specifying them here will mean less probing, if users try to watch them (the proxy will return cannot decode instantly and not bother the cards). This can significantly reduce failure-traffic in large shares, recommended for all profiles with or without service mapping enabled.
It probably makes little sense to set this globally as service ids are likely to be profile-specific (see below for overrides per profile).
NOTE: this is a performance tweak, not an access control feature! Blocked sids can still be watched by all users if they appear in the cache. By design the proxy has no limitations on what users can access, everything is meant to be fully available to everyone.

Example: <block-services>44f 43b 456 45f 421 452 44e 458 43d 45e 43c 3fd</block-services>

connection-manager/service-map/mapper/auto-reset-threshold

If the service mapper has determined that a particular service cannot be decoded by any card, but clients still keep sending ECM requests for it, this will determine how many such failures it would take before the mapper forgets the service status and tries all the cards again. Useful in case of glitches where services fail to decode for a short period (also see retry-lost-services). Setting a value too low could cause cards to be congested with probing, and setting it too high means users will have to wait longer before lost services are discovered again.
connection-manager/service-map/mapper/log-missing-sid

true/false (default: true). Log a warning for messages without SID. No SID means many of the proxy features won't work, and as of 0.6.2 clients that can't (or won't) include the SID will only work well in profiles where there is only one card connector (or where all cards have the same services). They may still function without obvious problems if they retry quickly upon receiving a cannot decode reply, but there is no guarantee that the proxy load balancing and service mapper will not route the requests to the same card repeatedly.
connection-manager/service-map/mapper/unknown-sid

Defines a special SID that will be sent to servers when SID is 0 (unknown). Client requests for this SID will also be treated as if it was 0. This can be used as a workaround for servers that require a non-zero SID, and for clients that send a fixed special SID instead of 0 when service is unknown (e.g cardlink). Make sure that this isn't set to a real SID that exists in the services file.
connection-manager/service-map/mapper/retry-lost-services

true/false (default: true). Whenever the service-mapper registers a service lost from a card that could previously decode it, it will register a background probe to see if it returns.
The status for the service on the particular card in question will be reset with an increasing interval (doubles every time, starting at 5 minutes after it was lost and ending if it hasn't been found after 48 hours). Under normal circumstances, you probably want to keep this switched on, for all profiles with service-mapping enabled.
NOTE: This only makes sense if there are multiple cards in the profile, otherwise lost services would be found within minutes when someone tried to watch them, through the auto-reset-threshold.
connection-manager/service-map/mapper/hide-unknown-services

true/false (default: false). Determines whether to hide services with no known names (sids that were not found in the services file for the profile) from the query api and hence the status web.
NOTE: If you're not using a services file, setting this to true would hide all services.
connection-manager/service-map/mapper (attributes: *profile, enabled)

When you use the mapper element with a profile attribute set, it allows overriding of any of the above mapper settings for a specific profile.
- profile: Name of the profiles that the overrides apply to, this profile must exist.
- enabled: true/false (default: true). Enable/disable service mapping entirely for this profile.
NOTE: See the end of README.txt for more information on service mapping.

Example:
<mapper profile="providerX" enabled="true">
<reset-services>51f 520 515</reset-services>
<block-services>44f 43b 456 45f 421 452 44e 458 43d 45e 43c 3fd</block-services>
</mapper>

connection-manager/external-connector-config (attributes: enabled)

Allows loading additional connector definitions from an external or remotely hosted file/url, with automatic checks for changes at a set interval. The remote file must contain xml with connector definitions exactly like in the cws-connector element (see below), but contained in a top level element called: external-cws-connectors (see connectors.example.xml).
Internally defined connectors take precedence over external ones, so if a connector in the external file has the same name as an already existing internal, it will be ignored.
- enabled: true/false (default: true). Disable/enable all external connectors and the auto fetch mechanism.
connection-manager/external-connector-config/connector-file-url

The url of the external connector file. Any valid url can be used, including https/ftp and user:passwd@hostname type auth info. File urls are also accepted.
connection-manager/external-connector-config/connector-file-key

Optional blowfish key. If this element is present, the connector file is assumed to have been encrypted using trtest.jar and this key.
connection-manager/external-connector-config/update-interval

How often to check for changes in the connector file (in minutes). Only if changes are detected is the file fetched and installed.
connection-manager/cws-connectors

This section contains the list of CW servers that the proxy should try to maintain a connection with.
connection-manager/cws-connectors/[newcamd-connector|radegast-connector] (attributes: *name, profile, enabled, qos-class)

Defines one newcamd or radegast CW server connection.
- name: Name of the connection. Just an arbitrary label to identify this particular card/cardserver, must be unique.
- profile: Which profile this connection belongs to. If this is not configured, the connector will only work if the card ca-id received on login matches the ca-id for exactly 1 defined profile (it will then be auto-assigned to this profile). In general profile should always be specified.
- metric: This is an integer value similar to interface metric used to determine preference when routing (here it is: 0 - 10, default 1). Lower is better. Take this scenario:

You have 4 cards, 2 stable ones on fast lan and 2 on wan. One of the wan cards is on a notoriously unstable connection. You want to make sure that the wan cards are only used when no other cards can decode the service, i.e force the load balacing to only use the lan cards whenever possible. You give the lan cards a metric of "1", the stable wan card "2" and the unstable one "3". Only when absolutely necessary will the load balancer use a higher metric connector (when the services to be decoded exist only there, or when the other cards are overloaded and wouldn't be able to handle one more request in time).

- enabled: true/false (default: true). Allows for disabling a connection without deleting it.
- qos-class: Integer value with the qos class to set for each outgoing connection (default: 16) or "none", to disable. Only disable or change this if the JVM fails to set the qos class (causing SocketExceptions with "Unrecognized option" when connecting).

Example: <newcamd-connector name="card3" profile="providerX" metric="2" enabled="true">

connection-manager/cws-connectors/[newcamd-connector|radegast-connector]/host

Hostname or IP for the CW server.
connection-manager/cws-connectors/[newcamd-connector|radegast-connector]/port

TCP port for the CW server.
connection-manager/cws-connectors/[newcamd-connector|radegast-connector]/can-decode-services

Optional list of sids (hex) that the service mapper should always consider as decode'able on this connector, regardless of what the server actually returns.
Under normal circumstances (with auto discovery working reliably) this element should not be used. To force auto-discovery of a service on a connector, use the reset commands on the status web (admin section) instead.

Example: <can-decode-services>44f 43b 456 45f 421 452 44e 458 43d 45e 43c 3fd</can-decode-services>

connection-manager/cws-connectors/[newcamd-connector|radegast-connector]/cannot-decode-services

Optional list of sids (hex) that the service mapper shouldn't bother looking for on this connector. NOTE: If the mapper has already auto-discovered a service on this connector, listing it here will not block it until old status has been cleared (either through a manual service reset via the status web or by deleting the .dat cache entirely for the profile, and restarting the proxy).
Under normal circumstances (with auto discovery working reliably) this element should not be used. To block services entirely for the whole profile, use the block-services element instead.
connection-manager/cws-connectors/newcamd-connector/user & pass

Credentials that the proxy will use when logging in to the CW server.
connection-manager/cws-connectors/newcamd-connector/des-key

Des key for the CW connection, overriding the default-des-key.
connection-manager/cws-connectors/newcamd-connector/keepalive-interval

Keep-alive interval, overriding the default-keepalive-interval.
connection-manager/cws-connectors/newcamd-connector/client-id

Client id bytes for newcs identification, overriding the default-client-id.
connection-manager/cws-connectors/newcamd-connector/au-users

List of user names allowed to update the card hosted by this connector (separated by space). All EMM's sent to the proxy by these users will be forwarded to this connector.
Unless you know a reason not to, try to ensure that one user is only ever configured to update one single card (any other setup can confuse the client). Additionally, it should only take one user per connector to keep it updated, under normal circumstances you shouldn't need to specify more.

Example: <au-users>testuser1 testuser2</au-users>

connection-manager/cws-connectors/newcamd-connector/asynchronous

true/false (default: false). Determines whether to use asynchronous mode. This can greatly increase efficiency for a connector, since all pending requests are sent immediately to the server, rather than sending one at a time and waiting for a response before sending again. Unless the server fails somehow when in asynchronous mode, set this to true.
See README.Optimization.txt for more details.
proxy-plugins

Allows for custom-written arbitrary plugins. See README.Plugins.txt for a description of the plugin api.
proxy-plugins/plugin (attributes: *class, enabled)

Defines one plugin for the proxy to load.
- class: Java class name for the plugin. A plugin must implement the interface com.bowman.cardserv.interfaces.ProxyPlugin and exist in the classpath to be loaded. See the example LoggingPlugin for tips.
- enabled: true/false (default: true). Allows enabling/disabling plugins while running.
- jar-file: Allows loading the plugin using a separate classloader, from an external jar file in the "plugins" dir. This way plugins can be replaced/reloaded at runtime without restarting the proxy (they are reloaded and restarted each time the proxy.xml config is touched/updated).

Example: <plugin class="com.bowman.cardserv.LoggingPlugin" enabled="true">

proxy-plugins/plugin/plugin-config

This is the arbitrary configuration that is supplied to the plugin, it may contain anything the plugin needs to do whatever it is that it does.
cache-handler (attributes: *class)

The cache handler is responsible for keeping track of which ECM's have been sent to cards and are currently awaiting CW, and for which ECM's the CW is already known. Exactly how to achieve this with maximum efficiency and error-handling is non-trivial so the entire cache implementation can be replaced with a customized version.
- class: Java class name for the cache class. It must implement the interface com.bowman.cardserv.interfaces.CacheHandler and exist in the classpath.
cache-handler/cache-config

This is the configuration supplied to the cache handler implementation, it can contain anything that the handler wants to make configurable.


There are two example cache implementations built in:
com.bowman.cardserv.DefaultCache - standard simple cache
com.bowman.cardserv.ClusteredCache - same as default but with realtime remote sharing over udp
See the example proxy-full.xml and README.ClusteredCache.txt for details on the various ways to configure the ClusteredCache.

 For the built in default cache the following settings are available:

cache-handler/cache-config/cw-max-age

The maximum age (in seconds) of an ECM -> CW mapping in the cache, before it can be deleted. In typical circumstances it would make sense to keep them at least 10-20 seconds.
cache-handler/cache-config/max-cache-wait

The maximum time (in seconds) that a client can be kept waiting in the cache for a pending request.
See README.Optimization.txt for more details.

The clustered cache (which is an extension of the default cache) has many additional settings, see README.ClusteredCache.txt for full docs.