Page tree

Documentation for Ice 3.5. The latest release is Ice 3.7. Refer to the space directory for other releases.

Skip to end of metadata
Go to start of metadata

On this page:

Glacier2.AddConnectionContext

Synopsis

Glacier2.AddConnectionContext=num

Description

If num is set to 1 or 2, Glacier2 adds a number of key-value pairs to the request context that it sends with each request. If num is set to 1, these entries are added to the context for all forwarded requests. If num is set to 2, the contexts are added only to calls to checkPermissions and authorize on permission verifiers, and to calls to create on session managers.

If num is non-zero, Glacier2 adds the following context entries:

_con.type

The type of the connection as returned by Connection::type.

_con.localAddress

The local address (TCP and SSL only).

_con.localPort

The local port (TCP and SSL only).

_con.remoteAddress

The remote address (TCP and SSL only).

_con.remotePort

The remote port (TCP and SSL only).

_con.cipher

The cipher (SSL only).

_con.peerCert

The first certificate of the client certificate chain (SSL only).

The default value is zero, meaning that no contexts are added.

Glacier2.AddSSLContext

Synopsis

Glacier2.AddSSLContext=num

Description

For sessions created with createSessionFromSecureConnection, this property, when set to a value greater than zero, instructs Glacier2 to provide additional information in the context of each request:

SSL.Active

If the client established an SSL connection to the router, this entry is present and has the value 1. This entry is not present if SSL was not used.

SSL.Cipher

A description of the ciphersuite negotiated for the SSL connection.

SSL.Remote.Host

The client's originating host name or address.

SSL.Remote.Port

The client's originating port number.

SSL.Local.Host

The router's local host name or address.

SSL.Local.Port

The router's local port number.

SSL.PeerCert

If the client supplied a certificate, this entry is present and contains the encoded certificate in PEM format.

Note that these SSL context entries are forwarded regardless of the setting of Glacier2.Client.ForwardContext.

If this property is not defined, its default value is zero.

This property is deprecated and supported only for backward-compatibility. New applications should use #Glacier2.AddConnectionContext.

Glacier2.AddUserToAllowCategories

Synopsis

Glacier2.AddUserToAllowCategories=num

Description

Specifies whether to add an authenticated user ID to the #Glacier2.AllowCategories property when creating a new session. The legal values are shown below:

0

Do not add the user ID (default).

1

Add the user ID.

2

Add the user ID with a leading underscore.

This property is deprecated and supported only for backward-compatibility. New applications should use #Glacier2.Filter.Category.AcceptUser.

Glacier2.Admin.AdapterProperty

Synopsis

Glacier2.Admin.AdapterProperty=value

Description

Glacier2 uses the adapter name Glacier2.Admin for its administrative object adapter. Therefore, adapter properties can be used to configure this adapter.

The Glacier2.Admin.Endpoints property must be defined to enable the administrative object adapter.

Glacier2's administrative interface allows a remote client to shut down the router; we generally recommend the use of endpoints that are accessible only from behind a firewall.

Glacier2.AllowCategories

Synopsis

Glacier2.AllowCategories=list

Description

Specifies a white space-separated list of identity categories. If this property is defined, then the Glacier2 router only allows requests to Ice objects with an identity that matches one of the categories from this list. If #Glacier2.AddUserToAllowCategories is defined with a non-zero value, the router automatically adds the user ID of each session to this list.

This property is deprecated and supported only for backward-compatibility. New applications should use #Glacier2.Filter.Category.Accept.

Glacier2.Client.AlwaysBatch

Synopsis

Glacier2.Client.AlwaysBatch=num

Description

If num is set to a value larger than zero, the Glacier2 router always batches queued oneway requests from clients to servers regardless of the value of their _fwd contexts. This property is only relevant when #Glacier2.Client.Buffered is enabled. The default value is 0.

Glacier2.Client.Buffered

Synopsis

Glacier2.Client.Buffered=num

Description

If num is set to a value larger than zero, the Glacier2 router operates in buffered mode, in which incoming requests from clients are queued and processed in a separate thread. If num is set to zero, the router operates in unbuffered mode in which a request is forwarded in the same thread that received it. The default value is 1.

Glacier2.Client.AdapterProperty

Synopsis

Glacier2.Client.AdapterProperty=value

Description

Glacier2 uses the adapter name Glacier2.Client for the object adapter that it provides to clients. Therefore, adapter properties can be used to configure this adapter.

This adapter must be accessible to clients of Glacier2. Use of a secure transport for this adapter is highly recommended.

Note that Glacier2.Registry.Client.Endpoints controls the client endpoint for Glacier2. The port numbers 4063 (for TCP) and 4064 (for SSL) are reserved for Glacier2 by the Internet Assigned Numbers Authority (IANA).

Glacier2.Client.ForwardContext

Synopsis

Glacier2.Client.ForwardContext=num

Description

If num is set to a value larger than zero, the Glacier2 router includes the request context when forwarding requests from clients to servers. The default value is 0.

Glacier2.Client.SleepTime

Synopsis

Glacier2.Client.SleepTime=num

Description

If num is set to a value larger than zero, the Glacier2 router sleeps for the specified number of milliseconds after forwarding all queued requests from a client. This delay is useful for batched delivery because it makes it more likely for events to accumulate in a single batch. Similarly, if overrides are used, the delay makes it more likely for overrides to actually take effect. This property is only relevant when #Glacier2.Client.Buffered is enabled. The default value is 0.

Glacier2.Client.Trace.Override

Synopsis

Glacier2.Client.Trace.Override=num

Description

If num is set to a value larger than zero, the Glacier2 router logs a trace message whenever a request was overridden. The default value is 0.

Glacier2.Client.Trace.Reject

Synopsis

Glacier2.Client.Trace.Reject=num

Description

If num is set to a value larger than zero, the Glacier2 router logs a trace message whenever the router's configured filters reject a client's request. The default value is 0.

Glacier2.Client.Trace.Request

Synopsis

Glacier2.Client.Trace.Request=num

Description

If num is set to a value larger than zero, the Glacier2 router logs a trace message for each request that is forwarded from a client. The default value is 0.

Glacier2.CryptPasswords

Synopsis

Glacier2.CryptPasswords=file

Description

Specifies the file name of a Glacier2 access control list. Each line of the file must contain a user name and a password, separated by white space. The password must be a 13-character crypt-encoded string. This property is ignored if #Glacier2.PermissionsVerifier is defined.

Glacier2.Filter.AdapterId.Accept

Synopsis

Glacier2.Filter.AdapterId.Accept=list

Description

Specifies a space-separated list of adapter identifiers. If defined, the Glacier2 router filters requests so that it only allows requests to Ice objects with an adapter identifier that matches one of the entries in this list.

Identifiers that contain spaces must be enclosed in single or double quotes. Single or double quotes that appear within an identifier must be escaped with a leading backslash.

Glacier2.Filter.Address.Accept

Synopsis

Glacier2.Filter.Address.Accept=list

Description

Specifies a space-separated list of address-port pairs. When defined, the Glacier2 router filters requests so that it only allows requests to Ice objects through proxies that contain network endpoint information that matches an address-port pair listed in this property. If not defined, the default value is *, which indicates that any network address is permitted. Requests accepted by this property may be rejected by the #Glacier2.Filter.Address.Reject property.

Each pair is of the form address:port. The address or port number portion can include wildcards ('*') or value ranges or groups. Ranges and groups have the form [value1, value2, value3, ...] and/or [value1-value2]. Wildcards, ranges, and groups may appear anywhere in the address-port pair string.

Glacier2.Filter.Address.Reject

Synopsis

Glacier2.Filter.Address.Reject=list

Description

Specifies a space-separated list of address-port pairs. When defined, the Glacier2 router rejects requests to Ice objects through proxies that contain network endpoint information that matches an address-port pair listed in this property. If not set, the Glacier2 router allows requests to any network address unless the #Glacier2.Filter.Address.Accept property is set, in which case requests will be accepted or rejected based on the Glacier2.Filter.Address.Accept property. If both the Glacier2.Filter.Address.Accept and Glacier2.Filter.Address.Reject properties are defined, the Glacier2.Filter.Address.Reject property takes precedence.

Each pair is of the form address:port. The address or port number portion can include wildcards ('*') or value ranges or groups. Ranges and groups have the form [value1, value2, value3, ...] and/or [value1-value2]. Wildcards, ranges, and groups may appear anywhere in the address-port pair string.

Glacier2.Filter.Category.Accept

Synopsis

Glacier2.Filter.Category.Accept=list

Description

Specifies a space-separated list of identity categories. If defined, the Glacier2 router filters requests so that it only allows requests to Ice objects with an identity that matches one of the categories in this list. If #Glacier2.Filter.Category.AcceptUser is defined with a non-zero value, the router automatically adds the user name of each session to this list.

Categories that contain spaces must be enclosed in single or double quotes. Single or double quotes that appear within a category must be escaped with a leading backslash.

Glacier2.Filter.Category.AcceptUser

Synopsis

Glacier2.Filter.Category.AcceptUser=num

Description

Specifies whether to add an authenticated user ID to the #Glacier2.Filter.Category.Accept property when creating a new session. The legal values are shown below:

0

Do not add the user ID (default).

1

Add the user ID.

2

Add the user ID with a leading underscore.

Glacier2.Filter.Identity.Accept

Synopsis

Glacier2.Filter.Identity.Accept=list

Description

Specifies a space-separated list of identities. If defined, the Glacier2 router filters requests so that it only allows requests to Ice objects with an identity that matches one of the entries in this list.

Identities that contain spaces must be enclosed in single or double quotes. Single or double quotes that appear within an identity must be escaped with a leading backslash.

Glacier2.Filter.ProxySizeMax

Synopsis

Glacier2.Filter.ProxySizeMax=num

Description

If set, the Glacier2 router rejects requests whose stringified proxies are longer than num. This helps secure the system against attack. If not set, Glacier2 will accept requests using proxies of any length.

Glacier2.InstanceName

Synopsis

Glacier2.InstanceName=name

Description

Specifies a default identity category for the Glacier2 objects. If defined, the identity of the Glacier2 administrative interface becomes name/admin and the identity of the Glacier2 router interface becomes name/router.

If not defined, the default value is Glacier2.

Glacier2.PermissionsVerifier

Synopsis

Glacier2.PermissionsVerifier=proxy

Description

Specifies the proxy of an object that implements the Glacier2::PermissionsVerifier interface for controlling access to Glacier2 sessions. The router invokes this proxy to validate the user name and password of each new session. Sessions created from a secure connection are verified by the object specified in #Glacier2.SSLPermissionsVerifier. For simple configurations, you can specify the name of a password file using #Glacier2.CryptPasswords.

Glacier2 supplies a "null" permissions verifier object that accepts any username and password combination for situations in which no authentication is necessary. To enable this verifier, set the property value to instance/NullPermissionsVerifier, where instance is the value of #Glacier2.InstanceName.

As a proxy property, you can configure additional aspects of the proxy using properties.

Glacier2.ReturnClientProxy

Synopsis

Glacier2.ReturnClientProxy=num

Description

If num is a value greater than zero, Glacier2 maintains backward compatibility with clients using Ice versions prior to 3.2.0. In this case you should also define Glacier2.Client.PublishedEndpoints to specify the endpoints that clients should use to contact the router. For example, if the Glacier2 router resides behind a network firewall, the Glacier2.Client.PublishedEndpoints property should specify the firewall's external endpoints.

If not defined, the default value is zero.

Glacier2.RoutingTable.MaxSize

Synopsis

Glacier2.RoutingTable.MaxSize=num

Description

This property sets the size of the router's routing table to num entries. If more proxies are added to the table than this value, proxies are evicted from the table on a least-recently used basis.

Clients based on Ice version 3.1 and later automatically retry operation calls on evicted proxies and transparently re-add such proxies to the table. Clients based on Ice versions earlier than 3.1 receive an ObjectNotExistException for invocations on evicted proxies. For such older clients, num must be set to a sufficiently large value to prevent these clients from failing.

The default size of the routing table is 1000.

Glacier2.Server.AdapterProperty

Synopsis

Glacier2.Server.AdapterProperty=value

Description

Glacier2 uses the adapter name Glacier2.Server for the object adapter that it provides to servers. Therefore, adapter properties can be used to configure this adapter.

This adapter provides access to the SessionControl interface and must be accessible to servers that call back to router clients.

Glacier2.Server.AlwaysBatch

Synopsis

Glacier2.Server.AlwaysBatch=num

Description

If num is set to a value larger than zero, the Glacier2 router always batches queued oneway requests from servers to clients regardless of the value of their _fwd contexts. This property is only relevant when #Glacier2.Server.Buffered is enabled. The default value is 0.

Glacier2.Server.Buffered

Synopsis

Glacier2.Server.Buffered=num

Description

If num is set to a value larger than zero, the Glacier2 router operates in buffered mode, in which incoming requests from servers are queued and processed in a separate thread. If num is set to zero, the router operates in unbuffered mode in which a request is forwarded in the same thread that received it. The default value is 1.

Glacier2.Server.ForwardContext

Synopsis

Glacier2.Server.ForwardContext=num

Description

If num is set to a value larger than zero, the Glacier2 router includes the request context when forwarding requests from servers to clients. The default value is 0.

Glacier2.Server.SleepTime

Synopsis

Glacier2.Server.SleepTime=num

Description

If num is set to a value larger than zero, the Glacier2 router sleeps for the specified number of milliseconds after forwarding all queued requests from a server. This delay is useful for batched delivery because it makes it more likely for events to accumulate in a single batch. Similarly, if overrides are used, the delay makes it more likely for overrides to actually take effect. This property is only relevant when #Glacier2.Server.Buffered is enabled. The default value is 0.

Glacier2.Server.Trace.Override

Synopsis

Glacier2.Server.Trace.Override=num

Description

If num is set to a value larger than zero, the Glacier2 router logs a trace message whenever a request is overridden. The default value is 0.

Glacier2.Server.Trace.Request

Synopsis

Glacier2.Server.Trace.Request=num

Description

If num is set to a value larger than zero, the Glacier2 router logs a trace message for each request that is forwarded from a server. The default value is 0.

Glacier2.SessionManager

Synopsis

Glacier2.SessionManager=proxy

Description

Specifies the proxy of an object that implements the Glacier2::SessionManager interface. The router invokes this proxy to create a new session for a client, but only after the router validates the client's user name and password.

As a proxy property, you can configure additional aspects of the proxy using properties.

Glacier2.SessionTimeout

Synopsis

Glacier2.SessionTimeout=num

Description

If num is set to a value larger than zero, a client's session with the Glacier2 router expires after the specified num seconds of inactivity. The default value is 0, meaning sessions do not expire due to inactivity.

It is important to choose num such that client sessions do not expire prematurely.

Setting the session timeout enables Active Connection Management (ACM) for client connections (by setting Glacier2.Client.ACM). By default, the ACM timeout is set to twice the session timeout. If no session timeout is defined, ACM is disabled.

Glacier2.SSLPermissionsVerifier

Synopsis

Glacier2.SSLPermissionsVerifier=proxy

Description

Specifies the proxy of an object that implements the Glacier2::SSLPermissionsVerifier interface for controlling access to Glacier2 sessions. The router invokes this proxy to verify the credentials of clients that attempt to create a session from a secure connection. Sessions created with a user name and password are verified by the object specified in #Glacier2.PermissionsVerifier.

Glacier2 supplies a "null" permissions verifier object that accepts the credentials of any client for situations in which no authentication is necessary. To enable this verifier, set the property value to instance/NullSSLPermissionsVerifier, where instance is the value of #Glacier2.InstanceName.

As a proxy property, you can configure additional aspects of the proxy using properties.

Glacier2.SSLSessionManager

Synopsis

Glacier2.SSLSessionManager=proxy

Description

Specifies the proxy of an object that implements the Glacier2::SSLSessionManager interface for managing sessions. The router invokes this proxy to create a new session for a client that has called createSessionFromSecureConnection.

As a proxy property, you can configure additional aspects of the proxy using properties.

Glacier2.Trace.RoutingTable

Synopsis

Glacier2.Trace.RoutingTable=num

Description

The routing table trace level:

0

No routing table trace (default).

1

Logs a message for each proxy that is added to the routing table.

2

Logs a message for each proxy that is evicted from the routing table (see #Glacier2.RoutingTable.MaxSize).

3

Combines the output for trace levels 1 and 2.

Glacier2.Trace.Session

Synopsis

Glacier2.Trace.Session=num

Description

If num is set to a value larger than zero, the Glacier2 router logs trace messages about session-related activities. The default value is 0.

  • No labels