Here's a run through of all the settings for cardservproxy 0.9.1, in the recommended order.

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/Conditional_access
- TS: Transport stream, http://en.wikipedia.org/wiki/Transport_stream
- CWS: Codeword server, aka cardserver. The server application (e.g newcs) that accept client connections and manages card communication.
- XML (element, attribute, xpath): http://en.wikipedia.org/wiki/Xml
- 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 (or one package in satellite terms). 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.

NOTE: as of 0.8.13 profiles use the original network-id (ONID) combined with ca-id as globally unique identifiers, meaning one profile now corresponds exactly to those pids from the transport stream that share the same ONID and caid.

Contents (element paths in bold represent common changes, anything else can be considered advanced tweaking):


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.9.1">
msg-enabled

** please complete documentation **

Example: <msg-enabled>true</msg-enabled>
msg-emu

** please complete documentation **

Example: <msg-emu>Mgcamd Acamd Evocamd</msg-emu>
msg-words

** please complete documentation **

Example: <msg-words>Welcome to CardServProxy</msg-words>
ca-profiles

A profile in the proxy corresponds to one type of card or provider/vendor. Each incoming message that is to be processed by the proxy must be assigned to a profile, either as a result of being received on a port that is locked to a profile or by mapping information (ca-id, provider idents, sid etc) in the request to information associated with the profile. The proxy can open listening-ports for each profile, and clients connecting to these will be assumed to only be sending traffic relevant to this profile (but there is no mechanism in the protocols that makes this happen, you have to make sure manually that all clients connecting to a port never send the wrong traffic).

CWS connectors can be 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). As of 0.9.0 multi-context connectors and ports are supported, but these only work for traffic that can be properly identified (i.e where the protocol or circumstances allow ca-id, network-id, provider-ident and sid to always be set correctly).

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. The proxy will gather card-information from all connectors in a profile (specifically provider-idents) and merge those automatically as long as there is no overlap. Cards with different ca-ids can never be included in the same profile.
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/default-deny-list

Optional global ip black list
A list of ip masks (wildcards supported) separated by space. This list applies to all defined profile listen ports and is checked first.

Example: <default-deny-list>192.168.66.* 10.0.0.7</default-deny-list>

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. See README.Optimization.txt for more details.

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/block-caid-mismatch

true/false (default: true) Block all replies where the request had a different ca-id. Determines whether M flag transactions are blocked or not (i.e returned as failures to the clients). Since the cache is global, it is possible for a client to send requests to the wrong port and still get valid replies (which may cause it to ignore the caid in the card-data and keep sending to the wrong port - potentially destroying the service mapping for that profile).

NOTE: As of 0.9.1, this will also apply to cross-profile cache hits that have the same ca-id (but where ecms were sent to different profiles). Such configurations with several profiles receiving the same traffic aren't really supported, but if you you know what you're doing and you're sure you understand the implications - it will continue to work as before if you set this to false.
ca-profiles/extended-newcamd (attributes: *listen-port, bind-ip, enabled, debug)

Defines a listener for the extended version of the newcamd protocol used between mgcamd and newcs, allowing multiple systems to be accessed over one session. This will behave like newcs does when chameleon is used, and mgcamd clients (or any other that implement these protocol extensions) will receive a list of multiple cards when connecting.
The proxy will compile the list of available cards (or rather ca-id/provider-ident pairs) when a new session is created, based on which connectors and profiles are available at the time. If new connectors/profiles are added or removed after the client has connected, the extended protocol allows them to receive real-time updates without having to reconnect.

NOTE: AU will work over this port, but only if the au-user in question is configured to only update a single card (across all profiles). If there are more, dummy data will be returned instead.

- listen-port: TCP port number.
- bind-ip: Optional local IP to bind the listener to (default: all - 0.0.0.0).
- enabled: true/false (default: true).
- debug: true/false (default: true).

Example: <extended-newcamd listen-port="5556"/>

ca-profiles/extended-newcamd/des-key

Overrides the default-des-key for the extended-newcamd listener.

Example:

<extended-newcamd listen-port="5556">
    <des-key>14 13 12 11 10 09 08 07 06 05 04 03 02 01</des-key>
</extended-newcamd>

ca-profiles/extended-newcamd/exclude-profiles

Optional list of profile names that are to be excluded from this port. Only use this if overlapping/ambigious profiles exist (where it is not possible to find a single profile based on only ca-id and provider-ident).
Every single defined profile has to have the correct ca-id and network-id for the extended-newcamd port to work (the logs will show which ones are at fault, otherwise). If the same exact ca-id + ident combo exists within multiple profiles, they cannot be combined on this port and one of them has to be excluded (if not configured here, then one will be excluded at random).

Example:

<extended-newcamd listen-port="5556">
    <exclude-profiles>profile1 testprofile</exclude-profiles>
</extended-newcamd>

ca-profiles/extended-newcamd/main-ca-id

Optional ca-id to display in the old (regular newcamd) card-data record shown to clients on connect. If there is a way to unambigiously merge provider idents for this id from multiple profiles, it can make it possible even for clients that don't support the extended protocol to use this port to access multiple contexts (as long as those all use the same ca-id). I.e: cccam's newcamd support.

Example: <main-ca-id>0500</main-ca-id>

ca-profiles/profile (attributes: *name, ca-id, network-id, enabled, debug, cache-only, provider-idents, require-provider-match)

One proxy profile definition. All traffic that you plan to pass through the proxy must be identified and bound to a profile (meaning you have to know where it came from and take steps to avoid users sending you the wrong traffic). In a satellite setup this may mean you have to manually list a large number of profiles to cover everything, one for each card vendor/network operator. It will no longer be enough to just know the ca-id and provider-idents involved.
NOTE: It is possible to define profiles with no listen ports at all, for use with extended-newcamd or csp-connect.

- name: Typically the provider/vendor name but can be any short string (case sensetive, may not contain spaces). Names are local labels and not transmitted when using csp-connect.
- ca-id: Assigns a ca-id to the profile. As of 0.9.0 this should always be set correctly to prevent accidentally merging multiple ca-ids within one profile. Can be set to 0000 only if you know it doesn't matter for your setup (i.e you have only one profile and don't intend to use csp-connect or extended ports). NOTE: This 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).

- network-id: Assigns a dvb network-id to the profile. This will be used to uniquely identify profiles between proxies (together with ca-id) and should always be set correctly. If you are unable to find out what the id is for your setup it can be left as 0000, but the profile will not be shared via csp-connect or accessible through extended-newcamd.

NOTE: This original dvb network id can be easily found if you have access to the enigma web of a dreambox, its the ONID value in the stream info/about. If you have an enigma services file handy you can find a service line you know belongs to the network in question and look at the third value from the right, for example in: 00aa:ffff0000:000e:0064:1:285 - 0064 is the network id.
If you don't have an enigma file (and you're unable to find some equivalent in your dvb application) you can use dvbsnoop to check the NIT data of the transport stream directly, for example: dvbsnoop -n 1 0x10 | grep Original_network_ID (0x10 is the pid for the NIT data, Network Information Table). Remember to tune to a transponder that belongs to the network in question before snooping.

- enabled: true/false (default: true) Allows for temporarily disabling one profile. Doing so will close all its listening ports, and also disable any connectors that explicitly reference this profile.
- 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. This is experimental and probably best left alone.
- provider-idents: Optional list of idents to associate with this profile. Normally these are provided by the card connectors you include in the profile and do not need to be specified. If you do list them, make sure you get it right. It determines what will be shown to clients connecting via csp-connect and the extended newcamd port (and what will be included in the card-data for any regular profile-specific listen port, unless overridden).
- require-provider-match: true/false (default: true, unless the profile contains the single ident 00 00 00 in which case the default is false). Set this to false if you know the provider idents do not matter for the ca-system used within this profile. Doing so will automatically add the ident 00 00 00 to the profile (if it wasn't manually added already).

Example: <profile name="cableVendorX" network-id="0064" ca-id="0b00" provider-idents="00 00 00, 00 00 01" enabled="true" debug="true" require-provider-match="false">

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

Defines a newcamd listener port for the profile. Multiple ports can be used in a profile, each with individual configurations.
- 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"/>

Example:

<newcamd listen-port="13112">
    <des-key>14 13 12 11 10 09 08 07 06 05 04 03 02 01</des-key>
    <card-data type="config" ca-id="0604"><provider-idents>00 00 00,00 00 01</provider-idents></card-data>
    <no-encryption>false</no-encryption>
    <no-validation>true</no-validation>
</newcamd>

ca-profiles/profile/newcamd/des-key

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

Example:

<newcamd listen-port="13112">
    <des-key>14 13 12 11 10 09 08 07 06 05 04 03 02 01</des-key>
</newcamd>

ca-profiles/profile/newcamd/card-data (attributes: *type, name, ca-id, 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, except with provider idents from any another cards (or from the provider-idents in the profile config) merged into it.

NOTE: As of 0.9.1 it should be possible to use configured card-data to trick clients with custom handling for tunneled systems (one ca-system within another) into sending you desired ecms, even when the profile and the connectors need to be set to another ca-id. Incoming messages will always be assigned the ca-id of the profile, even if the card-data for a particular port said something else.

- type: Set to either config, 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.
- ca-id: If type is config then ca-id can be set to a valid hex string, i.e: 0B00. If no ca-id is set for type config, the ca-id from the profile is used.
- 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"/>
Example: <card-data type="file" name="etc/mycard.card" override-au="true"/>
Example: <card-data type="config" ca-id="0604"><provider-idents>00 00 00,00 00 01</provider-idents></card-data>

ca-profiles/profile/newcamd/card-data/provider-idents

Only valid for type config. List of providers in comma-separated hex strings. If no list is specified, the card-data will contain the list of provider idents currently associated with the profile (if there is none 00 00 00 will be used). Only use this if you specifically want to override the provider idents that belong in the profile and show the client something else.

Example: <provider-idents>00 00 00,00 00 01,00 00 02</provider-idents>

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/newcamd/no-validation

true/false (default: false) Set to true and the proxy will ignore incorrect ca-id/provider-ident specified in the newcamd header. Only use this if you know a particular client is in fact sending the right ecms, but putting the wrong ca-id/ident in the header (or something else entirely, like the original newcamd client).

NOTE: If no-validation is true, the port cannot be used with clients that do include the correct caid/ident in the header (notably cccam), when the ident is relevant in the ca-system in question - since such information is lost with no-validation. I.e. if you wish to combine for example cccam and the original newcamd client in the same setup, you have to connect them to different ports, and set no-validation to true only for the one used by old newcamd.

Example: <newcamd listen-port="11112"><no-validation>true</no-validation></newcamd>

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, filter)

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), "cccam" (for CCcam.channelinfo), "dvbviewer" (for dvbviewer exports, ini-files), "neutrino" (services.xml) 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).
- filter: Optional and applicable for enigma, cccam, neutrino and dvbviewer formats. This filter tells the proxy that only service definitions matching these listed strings should be parsed for this profile. What the filter is matched against depends on the format

For a cccam channelinfo file this should be a list of provider idents separated by space, i.e: 000000 022F00 030B00 (but there is typically no need to set this if provider-idents have been listed for the profiles, if so those will be used).

For a dvbviewer ini file (export) this is matched against the "Root" key of each channel section (case sensetive). It should not be necessary to filter if network-id can be properly specified for the profile.

For a neutrino services.xml the filter strings are comma separated and matched against the satellite names (case insensetive, from the beginning of the name). It should not be necessary to filter if network-id can be properly specified for the profile.

For enigma services files from dvb-c/t the 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.

NOTE: As of 0.8.13 enigma services files will be automatically filtered on network-id (if set for the profile) so filtering on the provider strings in enigma files shouldn't be necessary for most situations. If you DO set a filter string, network-id will not be used for filtering.

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 comma). 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 filter="name with spaces, vendor X, vendor Y">etc/services</services-file>
Example: <services-file format="simple">etc/servicesForProfileX.properties</services-file>
Example: <services-file format="cccam" filter="022F00 030B00">etc/CCcam.channelinfo</services-file>
Example: <services-file format="dvbviewer">etc/dvbviewer.export.ini</services-file>
Example: <services-file format="neutrino">etc/services.xml</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, but if clients have a lower timeout value that can't be easily reconfigured - setting it lower may be necessary (meaning cannot-decode replies will start happening earlier as connector queues grow).
Applies to all CWS connectors in this profile, if set here it overrides the global setting in connection-manager.

NOTE: When using multi-context connectors (e.g csp-connector or chameleon-connector) the max-cw-wait in effect is the global value, not the per profile one.

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.

Example: <max-cw-wait>7</max-cw-wait>
Example: <max-cw-wait>3900 ms</max-cw-wait>

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.

NOTE: If max-cw-wait is below 1s, congestion-limit is automatically set to the same value.
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.

NOTE: For any non-trivial live setup with multiple users, it will likely become necessary to turn all off ecm/emm/zap logging once initial configuration is completed and verified to be working. Use the debug flag for individual users instead to do live tracing.

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

NOTE: All levels beyond FINE are extremely verbose and cannot really be used in a live multi-user environment, it will eventually crash or at the very least alter the behavior you were trying to trace.
Level FINE should be ok for a while however, enabling short term troubleshooting under most circumstances.
Level INFO (or in extreme cases WARNING) should be used as default for all non-trivial traffic loads.

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

logging/log-dateformat

Optional alternate format string to use for the logging. Must be a valid java SimpleDateFormat pattern.

Example: <log-dateformat>yyMMdd HH:mm:ss.SSS</log-dateformat>

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).
- include-file-events: true/false (default: true). Controls whether to gather all file loggings with level WARNING and SEVERE for display in the web-backend (file-log status query). Visible to admin users only.

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

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). You will need to change this to run multiple proxies on the same host, even if nothing makes use of RMI in your setup.
rmi/local-port

TCP port for the proxy remote api object (default: 4098). You will need to change this to run multiple proxies on the same host, even if nothing makes use of RMI in your setup.
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/bind-ip

Optional local IP to bind the listen port to (default: all - 0.0.0.0).
rmi/status-web/ssl (attributes: enabled)

Enable to use https instead of http (enabling/disabling ssl requires a proxy restart).

- 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 (enabling/disabling ssl requires a proxy restart). 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

NOTE: As of 0.9.0 there is a control command in the admin page of the status web for automatically generating a keystore file.

- 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/csp-connect (attributes: enabled, debug, ignore-cache-requests)

Allows disabling of csp-connections (csp-connectors from other proxies).
Csp-connections are always asynchronous and allow users access to all profiles (that they have access to according to the user-manager) over a single tcp connection. As the httpd is used to receive connections initially, enabling ssl is recommended (without https the credentials are sent in the clear).

- enabled: true/false (default: true)
- debug: true/false (default: true). Corresponds to the debug attribute for regular ca-profiles and determines whether to keep the transaction backlog for troubleshooting.
- ignore-cache-requests: true/false (default: false). Set to true to ignore clients requests for udp cache updates (even when ClusteredCache is in use locally).
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>

rmi/status-web/super-users

List of user names (separated by space) that should have access to the Config and Admin sections (control commands). Users must have admin set to true or they will be ignored.
NOTE: Users with admin set to true will still have access to other admin features in the web, even if they are not listed here.

Example: <super-users>root admin</super-users>
user-manager (attributes: *class, allow-on-failure, allow-different-ip, log-failures, jar-file)

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).
- 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.
- allow-different-ip: true/false (default: false). Allows duplicate Newcamd connections / sessions from different IP sources. The max-connection setting was still in effect when using this option.
- log-failures: true/false (default: false). Log login failures.
- jar-file: Allows loading the user-manager class via a separate classloader, from an external jar file in the "plugins" dir. This should make it easier to handle custom implementations. If jar-file is omitted, the system classloader is used (as in all versions before 0.8.10).

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/open-access (attributes: enabled)

Allows optional open newcamd access for the SimpleUserManager (also works for the XmlUserManager). Logins that match the open criteria will have temporary users with a random name created on the fly, and these are only valid for newcamd access. The login name actually specified by the client is replaced with a semi-random string to make them all unique. I.e. use this if you don't want any usermanagement at all, or wish to use the same user/pass for all clients.
- enabled: true/false (default: true). Set to false or remove the open-access element to disable.

NOTE: The temporary users will be ignored by the "last-seen" log, and will have the display-name set to whatever they tried to login as.

Example:

<open-access enabled="true">
  <open-username-prefix>csp-</open-username-prefix>
  <open-password>publicaccess</open-password>
  <open-profiles>profile2 profile3</open-profiles>
</open-access>
user-manager/auth-config/open-access/open-username-prefix

Only allow open access if the login username starts with this string (remove or leave empty to allow any username).
user-manager/auth-config/open-access/open-password

The password all open user logins must use.
user-manager/auth-config/open-access/open-profiles

Optionally restricts open access to only the listed profile names (separated by space, remove or leave empty and open access will apply to all profiles).
user-manager/auth-config/user (attributes: *name, *password, display-name, ip-mask, profiles, max-connections, admin, enabled, start-date, expire-date, spider, ecm-rate)

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.
- display-name: An optional non-unique alias for the user (used by the http/xml api).
- 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 (? *), but this should typically not be used for users with dynamic ips - fixed only (no dns reverse lookups are performed, hostname masks will not be allowed).
- 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. NOTE: as of 0.9.0 this has changed to max-connections per profile, meaning and old values will likely need to be changed. Since it is no longer the total number of connections, the value should now reflect the number of clients/boxes the user is expected to connect with (regardless of how many profiles the user has access to) .
- 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.
- start-date: (dd-mm-yyyy) Start date for user account.
- expire-date: (dd-mm-yyy) Date after the user account expires.
- spider: true/false (default: true) ** please complete documentation **
- ecm-rate: ** please complete documentation **
- 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).

Example: <user name="usr1" password="secret" display-name="User one" profiles="profile1 otherprofile" max-connections="3" enabled="false"/>
Example: <user name="usr2" password="secret2" display-name="User two" profiles="otherprofile" max-connections="1" map-exclude="true"/>
Example: <user name="admin" password="secret3" display-name="Administrator" admin="true" debug="true"/>

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 3 seconds (anything lower will result in the default of 60 secs).

NOTE: If you have connectors that sporadically seem to get stuck and never reconnect, it very likely means you have this set too low.

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, but if clients have a lower timeout value that can't be easily reconfigured - setting it lower may be necessary (meaning cannot-decode replies will start happening earlier as connector queues grow).
This is the default for all CWS connectors in all profiles.

NOTE: When using multi-context connectors (e.g csp-connector or chameleon-connector) the max-cw-wait in effect is always this global value, not the per profile one.

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. Applies to all outgoing connections made by newcamd and chameleon connectors.

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>

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.

NOTE: If max-cw-wait is below 1s, congestion-limit is automatically set to the same value.
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 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 when you have more than one profile, as service ids are very likely to be profile-specific (see below for overrides per profile).

NOTE: By listing services here, you're indicating to the proxy that you expect the decode-status for them to change over time - so you will no longer receive "lost service" warnings when they suddenly stop working. In fact seeing repeated lost service warnings for a specific service or group of services is a good indication that you should probably list them in reset-services.

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. NOTE: As of 0.9.0, if the system used in the profile has additional significant information besides just sids (such as provider-idents or irdeto-chids) this must also be specified, using this syntax: sid:ident, sid:chid, sid:ident:chid or sid:chid:ident (e.g: 0000:000000, 0000:0000, 0000:000000:0000 or 0000:0000:000000).

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>
Example: <block-services>0438:020500 038e:020500 03ca:020500 0384:020500 0488:020500 02e4:020500 03a2:020500</block-services>

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

Some clients who are unable to known the real sid (i.e typically hardware solutions) send fixed dummy sids instead of 0. To make sure these aren't treated as real sids by the service mapping, list any such dummy sids here.

NOTE: The first sid listed here will also be used when forwarding unknown sid request to connectors, so if you want unknown forwards to keep the sid 0 - set 0 as the first entry in this list. If for some reason you absolutely want to retain the original dummy-services in the forwards too, set -1 as the first entry.

Example: <dummy-services>0 101 1101</dummy-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/broadcast-missing-sid

true/false (default: false). Enable this to have ecms without sid always forwarded to all non-congested connectors in the profile (as of 0.9.0 causing '2' flags for the affected transactions). Experimental: if there are many clients that cannot send sid, this will significantly increase traffic on the cards. Additionally, even if the broadcasting gets a valid reply the client may still have to perform at least one retry to get it.
connection-manager/service-map/mapper/redundant-forwarding

true/false (default: false). If this is true, the proxy will pick two connectors for each forward instead of just one (assuming there are at least two available). The ideal candidate will still be considered the primary choice, but the secondary will also receive the same forward (triggering transaction flag '2').
Secondary forwards are treated like probes, they are only carried out if there is unused capacity. If the secondary forward gets a reply before the primary, the transaction will end up with the flags '2FC' since the result is obtained through the cache (in the statistics these will still be counted only as forwards however).

NOTE: This will significantly increase the load on connectors (up to double) but should improve reliability if you have issues with individual connectors failing sporadically or their network being unstable.
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 mainly helps when there are multiple cards in the profile, if there is only one then 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/hide-disabled-connectors

true/false (default: false). Determines whether to hide disabled connectors from the query api and hence the status web.

NOTE: Disconnected or disabled connectors without a profile assigned will always be hidden regardless of this setting.
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 fishenc.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, provider-idents, metric, enabled, qos-class, override-checks)

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, and for radegast it is mandatory.
- provider-idents: Optional list of provider-idents (comma separated), overriding those this connector receives from the server. Only use this if you know the server is wrong, or need to exclude some unimportant idents to avoid them being associated with the profile. For radegast, this list is mandatory.
- 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).
- override-checks: true/false (default: false). Set to true to disable all validation of the card-data (only applies to newcamd). If you have problems with cards sometimes being disabled on connect you could try this, but usually that is an indication of a problem at the server end that should be investigated and eliminated there. It also allows you to force a connector into a profile even when the remote ca-id doesn't match.

Example: <newcamd-connector name="card3" profile="vendorX" metric="2" enabled="true">
Example: <radegast-connector name="card4" profile="vendorY" provider-idents="00 00 00, 01 01 01, 02 02 02" 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 (attributes: exclusive, profile)

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.

NOTE: As of 0.9.0, if the system used in the profile has additional significant information besides just sids (such as provider-idents or irdeto-chids) this must also be specified, using this syntax: sid:ident, sid:chid, sid:ident:chid or sid:chid:ident (e.g: 0000:000000, 0000:0000, 0000:000000:0000 or 0000:0000:000000).

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.
- exclusive: true/false (default: false). Set to true to indicate that no probing should be done for this connector, i.e that anything not explicitly listed in can-decode should be assumed to be cannot-decode.
- profile: Only applicable for multi-context connectors (chameleon-connector, csp-connector). Since these connector types have multiple profiles, it is necessary to indicate which profile each can-decode-services element is for (multiple lists supported).

Example: <can-decode-services exclusive="true">44f 43b 456 45f 421 452 44e 458 43d 45e 43c 3fd</can-decode-services>
Example: <can-decode-services>0438:020500 038e:020500 03ca:020500 0384:020500 0488:020500 02e4:020500 03a2:020500 0456:020500</can-decode-services>
Example: <can-decode-services profile="someprofile">421 452 44e 458</can-decode-services>

connection-manager/cws-connectors/[newcamd-connector|radegast-connector]/cannot-decode-services (attributes: profile)

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.
- profile: Only applicable for multi-context connectors (chameleon-connector, csp-connector). Since these connector types have multiple profiles, it is necessary to indicate which profile each can-decode-services element is for (multiple lists supported).
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 EMMs sent to the proxy by these users will be forwarded to this connector.
One user can only update a single card (per profile). If you want to use a single box/client to update multiple cards, you need to create several user accounts and have the client connect once for each account (the sessions will receive different card-data depending on the user name). Not all clients support multiple connections to the same server with only different login credentials to separate them.

NOTE: As of 0.9.0, changes to this element will take effect immediately (existing sessions for affected users will be kicked if needed). Additionally, the target connector for any given au-session is shown by name in the sessions list (emm count column).

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.
connection-manager/cws-connectors/newcamd-connector/caid-profile-map

If no profile is set for the connector, that implies you don't know what card will be at the server end (or the card changes randomly over time) and you wish the card to be assigned to a profile automatically based on ca-id.
This element allows you to specify a mapping table, with entries like "caid=profilename" that tells the proxy what to do depending on which remote card it finds when connecting. If a card is found with a ca-id that isn't in your map, the connector will enter its reconnect loop and remain offline until the card changes.

Example: <caid-profile-map>0b00=cable 0500=terrestrial</caid-profile-map>

connection-manager/cws-connectors/csp-connector (attributes: *name, metric, enabled, qos-class)

Defines one csp connection (to another proxy). Note that these differ from the other connector types in that they do not have a profile association, they're always bound to all profiles (or rather, those profiles that have a correct network-id and ca-id set, the rest are ignored).
Csp-connections are established using the httpd of the target proxy, but then switches to a fully asynchronous protocol (while keeping the same connection, so ssl remains if enabled). The service mapper states of remote proxies connected in this way will be communicated automatically on connect (and as changes occur).
Each proxy is assigned a random id every time it is restarted, that is used to prevent loops where ecm requests end up forwarded back to the proxy that originally received it.
A remote context received through a csp-connector is not relayed. E.g: if you connect one proxy to another with csp-connect, you will only see the locally defined connectors there (not anything it may have received from another csp/chameleon-connection of its own).

NOTE: If the user account at the target proxy has profile restrictions, the connector will not see all available network-ids, just the ones allowed by the remote user-manager.

- name: Name of the connection. Just an arbitrary label to identify this particular proxy connection, must be unique.
- metric: This is an integer value similar to interface metric used to determine preference when routing (here it is: 0 - 10, default 1).
- 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:

<csp-connector name="otherproxy" enabled="true">
    <url>https://remote.proxy.com:8443</url>
    <url-backup>https://backup.proxy.com:8443</url-backup>
    <user>user1</user>
    <password>user1pw</user>
    <exclude-profiles>unwantedprofilename1 unwantedprofilename2</exclude-profiles>
    <request-cache-updates>false</request-cache-updates>
</csp-connector>

connection-manager/cws-connectors/csp-connector/url

Url to connect to (i.e the root location of the status web for the remote proxy). If ssl is enabled at the remote proxy (recommended), this will be a https url.

NOTE: Do not attempt to specify the login credentials in the url, use the separate user/password elements for this.

Example: <url>https://remote.proxy.com:8443</url>

connection-manager/cws-connectors/csp-connector/url-backup

Optional: Url to the backup mirror of the remote proxy. This is just a shortcut that results in defining two connectors with one config. The backup is given the same name as the primary, but with the suffix "-backup". All other settings will be the same for the backup-connector (so the user account must exist on both target proxies).

Example: <url-backup>https://backup.proxy.com:8443</url-backup>

connection-manager/cws-connectors/csp-connector/request-cache-updates

If true (default false), sends the local ClusteredCache port to the remote proxy on connect. If it is also using ClusteredCache it will send udp cache updates to this port (for all its locally processed traffic, so may be bandwidth intensive over time).
connection-manager/cws-connectors/csp-connector/exclude-profiles

List of profile names that should not be mapped for this connector, even when their network-id + ca-id match.
connection-manager/cws-connectors/chameleon-connector (attributes: *name, metric, enabled, qos-class)

Defines one extended newcamd connection specifically for accessing multiple systems in one session (as supported by newcs/mgcamd). Despite the name, this does not use the chameleon protocol. It only uses the same newcamd extensions that allows mgcamd to access multiple cards from one newcs (this newcs in turn then uses chameleon2 to connect to to other newcs instances).
Note that these differ from the other connector types in that they do not have a profile association, they're always bound to all profiles (or rather, those profiles that have a correct network-id and ca-id set, the rest are ignored).

For chameleon-connector, there is an additional requirement in that the profiles must have provider-ident lists associated with them (either from manually specifying them using the 'provider-ident' attribute introduced in 0.9.0, or from live connectors to actual cards that are bound to the profile).
A list of ca-ids and provider-idents is returned from newcs to this type of connector, and only those ca-id/ident pairs that can be mapped to exactly one (1) profile will actually be used by the proxy. The rest will be ignored (but visible in the remote-properties for the connector, in the status web).

NOTE: If you have profiles without active connectors and would like to map them to what is available through a chameleon-connector, you must manually list all the provider-idents that are relevant for the profile using the provider-ident attribute (so you have to know which ones are on the cards).

- name: Name of the connection. Just an arbitrary label to identify this particular newcs connection, must be unique.
- metric: This is an integer value similar to interface metric used to determine preference when routing (here it is: 0 - 10, default 1).
- 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:

<chameleon-connector name="newcs" enabled="true">
    <des-key>01 02 03 04 05 06 07 08 09 10 11 12 13 14</des-key>
    <host>192.168.2.113</host>
    <port>5354</port>
    <user>user1</user>
    <password>user1pw</user>
    <profiles>satprofile1 satprofile2</profiles>
</chameleon-connector>

connection-manager/cws-connectors/chameleon-connector/profiles

Optional list of profile names that should be mapped for this connector (use this to avoid ambigious situations when there are multiple profiles using the same ca-id/ident pairs). If nothing is listed then all defined profiles are mapped.

NOTE: If you DO have profiles that share one or more ca-id/ident pairs then this list is mandatory, or the connector will accept no traffic (and remember that provider idents are associated with profiles not only from manual config but also automatically - based on card-data received from servers that are part of the profile - unless this is manually overridden).

Example: <profiles>satprofile1 satprofile2</profiles>

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. 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, and as of 0.8.11: when the plugin jar itself 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. If the plugin requires no special config (or if the defaults suffice), this can be omitted entirely.
cache-handler (attributes: *class, jar-file)

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.
- jar-file: Allows loading the cache class via a separate classloader, from an external jar file in the "plugins" dir. This should make it easier to handle custom implementations. If jar-file is omitted, the system classloader is used (as in all versions before 0.8.10).
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.

NOTE: As of 0.9.0, this can also be configured with a percentage string, e.g "50%" to indicate a max-cache-wait of 50% of the max-cw-wait for the request. This makes more sense when using profiles with radically different max-cw-waits in the same proxy (e.g some with 9 seconds and others with 650 ms).
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.