Wire listener REGISTER command

Registers application users with the wire listener. You must register application users by using the wpListener -register command before you start the wire listener.

Syntax diagram

Command parameters

-registrationFile registration_file

This parameter specifies the path and name of the registration file.

-action action

This parameter specifies an action:

addUser: Add a user ID and password combination.
removeUser: Remove a user ID and password combination.
changeUser: Change a user ID and password combination.
configureInstance: Sets properties for the wire listener instance.
configureSchema: Sets properties for a schema (JSON namespace)

Instance properties

-accessType local | message | remote: Sets the type of access. Local is the default. If you choose local, the registry file is updated only with the wire Listener -register command. If you choose message, the registry file is updated with listener requests, but only if the requesting user has administration privileges.
-context none | use: Sets the use of trusted context. None is the default. If you switch -context from use to none any existing context user associations are not affected. With none any such existing definition are ignored.

Schema properties

-schema schema: Specifies the db (schema) to which the selected action can apply.
-authenticate yes | no: Sets whether authentication is used for the schema. Authentication can be turned on for the instance level, but turned off on db (schema) level.
-context none | use: Sets the use of trusted context. None is the default. If you switch -context from use to none any existing context user associations are not affected. With none any such existing definition are ignored.
-contextUser none | username: Specifies the context user. None is the default. If this parameter is used, the user name must be a member of the DB2USERS group. If the useContext flag is explicitly or implicitly set for a db (schema) and the -contextUser parameter is set to none or not assigned, the user name sending the request is set as context user.
-dbOwner username: Specifies the database owner. An optional field for informational purposes.

User properties

-user userid

This parameter specifies the application user ID to register with the wire listener.

-password password

This parameter specifies a password for the application user ID to register with the wire listener.

-contextUser none | username

Specifies the context user. None is the default. If this parameter is used, the user name must be a member of the DB2USERS group. If the useContext flag is explicitly or implicitly set for a db (schema) and the -contextUser parameter is set to none or not assigned, the user name sending the request is set as context user.

-roles position 1| position 2| position 3| position 4

Specifies the user authorization for the selected scope as a four-character field

Position 1 r or 1: To assign read authorization
Position 2 w or 1: To assign write authorization
Position 3 d or 1: To assign collection management authorization
Position 4 u or 1: To assign user administration authorization

Use 0 or - in a position to exclude a specific right.

For example, r--- assigns reader rights, but excludes all other right. Another example is, 11--, or 1100 assigns read and write rights, but excludes all other rights. See the usage notes for further examples.

The listener role assignment is independent of Db2® authorizations. If a user has a reader role on a db (schema), a write request is rejected even if the user has all rights in the Db2 database.

Usage notes

The registry file contains instance-, schema-, and user-level directives for the wire listener. Authentication and context use can be turned on or off on instance and schema level.

User authentication and authorization information can also be supplied on instance and schema level. If a role is defined on instance or on schema level, requests from the user is validated against the role information before the request is sent to the Db2 database. Otherwise, the requested is routed to the Db2 database without a listener role check. That is, without listener role definitions the authorization is deferred to the Db2 server.

If no information is specified for a user on schema level, the instance level is used if it exists. This allows assigning selective listener-controlled access if user information is only set for some schemas.

The following matrix provides an example:

Table 1. . Selective listener-controlled access
	Instance	Schema X	Schema Y
User A	r---	(not set)	(not set)
User B	(not set)	rw--	(not set)
User C	rw--	(not set)	r---

User A has read access for all schemas. User B has read and write access to schema X, while requests on schema Y are routed to the Db2 database without a listener role check. User C has read access to schema Y, and read and write for all others.

On Linux® and UNIX systems, the registration file is a restricted file access privileges.

Example

In the following example, user app1 has read and write access to schema test, but read only access to all other schemas.

wplistener -register -registrationFile /home/acme/register.cfg -action add -user app1 -password mytoken -roles r---

wplistener -register -registrationFile /home/acme/register.cfg -action add -user app1 -password mytoken -schema test -roles rw--