streamtool mkdomain

Usage

mkdomain [-d,--domain-id <did>] [--admin-grp <group>] [--user-grp <group>] [--property <name=value>] ... [--hfile <host-file>] [--propfile <property-file>] [--ldap --server-url <url> --user-dn <dn-pattern> [--owner <owner>] [--user-secondary-lookup <element-name>] [--group-obj <ldap-class> --group-srch <DN> [--group-attr <element-name>] [--user-attr <element-name>]]] [--iam --iam-client-id <client-id> --iam-client-secret <client-secret> [[--iam-authz-endpoint-url <url>] [--iam-token-endpoint-url <url>] [--iam-jwks-endpoint-url <url>] [--iam-logout-endpoint-url <url>]]] [-h,--help] [--trace <level>] [-v,--verbose <level>] [--zkconnect {<host>:<port>},... | --embeddedzk]

The streamtool mkdomain command creates a domain.

Authority

You do not need any authority to run this command.

Description

You must create a domain before you can create instances. A domain can contain one or many instances. You can register artifacts such as available resources, users, and security information for use in the domain. The instances in a domain share a common security model and authentication server.

When you create a domain, you must specify an identifier that satisfies the following requirements:

  • The name must contain alphanumeric characters. You cannot use the following alphanumeric characters: ^!#$%&'*+,/;<>=?@[]`{|}˜(). You also cannot use the following Unicode and hexadecimal characters: u0000; u0001-u001F; u007F-u009F; ud800-uF8FF; uFFF0-uFFFF; x{10000}-x{10FFFF}.
  • The name cannot be zookeeper.
  • The maximum length of the name is 255 bytes.
  • The name must be unique among the domains that are defined by you, the domain owner, within ZooKeeper. If a resource is allocated to two or more domains that have the same name, this situation causes problems with the log files. The problem occurs irrespective of whether the domains are in the same ZooKeeper ensemble. Use unique domain names or ensure that the domainLog.path domain property value is unique for domains that have the same name.

By default, the domain is configured to use the Pluggable Authentication Module (PAM) for authenticating users. You can customize the PAM settings by altering the security.pamServiceName domain property. To use the Lightweight Directory Access Protocol (LDAP) for authenticating users, specify the --ldap command option. If the LDAP server is not configured to enable anonymous binds and the domain uses the --user-secondary-lookup option, you must take extra steps so that Streams can search LDAP information for users. In particular, you must set the LDAP administrator authentication credentials for the domain by using the following command parameters: --property security.ldapAdministratorUser=user --property security.ldapAdministratorPassword=password. To later change the LDAP administrator credentials, run the streamtool setldapadminconfig command. For more information about setting up security for Streams, see the product documentation.

By default, members of the DomainAdministrator role can administer the domain and members of the DomainUser role can use the domain. If you specify the --ldap and --owner options, the user that you specify in the --owner option is added to the DomainAdministrator role. Otherwise, the user that runs the streamtool mkdomain command is added to the DomainAdministrator role. The group that is specified in the --admin-grp option is also added to the DomainAdministrator role. The group that is specified in the --user-grp option is added to the DomainUser role.

All persistent data that is associated with domains and instances is stored by using ZooKeeper. The domain also contains a Java Management Extensions (JMX) server and Streams Console.

A domain can contain one or many hosts, which are referred to as resources. You can allocate hosts to a domain by running the streamtool registerdomainhost command before or after you create the domain. If you run the streamtool mkdomain command with the --hfile option, Streams starts the domain controller service on the specified hosts.

Tags are a mechanism for differentiating and identifying resources that have different physical characteristics or logical uses. Resources can have any number of tags. Tags are case-sensitive strings with a letter optionally followed by alphanumeric or underscore characters.

Streams defines the following tags:

application
Specifies that the resource can run Streams applications.
audit
Specifies that the resource can run the logging service.
authentication
Specifies that the resource can run the authentication and authorization service.
jmx
Specifies that the resource can run the management API service.
management
Specifies that the resource can run any of the Streams domain and instance management services.
sws
Specifies that the resource can run the web management service.
view
Specifies that the resource can run the view service.

You can define extra tags that meet your needs.

The domain maintains a registry of the tags that are defined in the domain.

If you have a long list of command options and domain properties, you can use the --propfile option. This option is also helpful if you want to use the same set of options or properties in multiple streamtool mkdomain commands.

The following commands are examples of the simplest mkdomain commands:

streamtool mkdomain -d domain1 --zkconnect hostA:1234 streamtool mkdomain -d domain2 --embeddedzk

The -d option specifies the domain name and the --zkconnect option specifies a comma-separated list of host and port pairs, which is used to connect to a ZooKeeper ensemble for the domain. The --embeddedzk option specifies to use the embedded ZooKeeper in Streams.

Consider specifying a unique path for the log and trace files for your domain. For example, specify 
--property
domainLog.path=/filepath/
. Otherwise, the log path defaults to the /tmp/Streams-domain_name directory, which might cause problems if this resource is used by multiple domains of the same name. If the directory that you specify does not exist on all of the resources in the domain, Streams tries to create it when the domain starts. If the user that starts the domain does not have authority to create the directory, the directory creation fails and Streams uses the default log path.

Options

--admin-grp <group>
Specifies a group whose members can administer the domain. This group is added to the DomainAdministrator role. If this option is not specified, only the following users can administer the domain:
  • Users that have the DomainAdministrator role.
  • The user that ran the streamtool mkdomain command, or the user that is specified in the --owner option.
-d,--domain-id <did>
Specifies the domain identifier.

If you do not specify this option, Streams uses the domain name that is set in the STREAMS_DOMAIN_ID environment variable. By default, that domain name is StreamsDomain. If you are using the interactive streamtool interface, it uses the name of the active domain for the current streamtool session or else it prompts you for the domain name.

The active domain for the current streamtool session is set every time that you successfully run a streamtool command with a -d or --domain-id option. Alternatively, you can run the streamtool domain command in the interactive interface.

--embeddedzk

Specifies to use the embedded copy of ZooKeeper. This option is not supported within the interactive streamtool interface.

If you are not using the interactive streamtool interface and you do not specify either this option or the --zkconnect option, Streams uses the ZooKeeper connection that is associated with the active domain or the domain that is specified in the --domain-id option. Streams determines which connection maps to the domain by using cached information about the domains. In this scenario, if the domain identifier is not unique in the Streams configuration cache, the command fails.

--group-attr <element-name>
Specifies the LDAP name of the element in the group record that contains the list of members in the group.

If you specified:

  • --group-objgroupOfNames, this option defaults to a value of member.
  • --group-obj groupOfUniqueNames, this option defaults to a value of uniqueMember.
  • --group-obj posixGroup, this option defaults to memberUid.
--group-obj <ldap-class>
Specifies the group object class to use when you search for group names in LDAP. The following classes are common object classes: groupOfNames; groupOfUniqueNames; posixGroup.
--group-srch <DN>
Specifies the base Distinguished Name (DN) to use when you search for group names in LDAP. For example: "ou=Groups,ou=streams,o=ibm.com".
-h,--help
Specifies to show the command syntax.
--hfile <host-file>
Specifies the path to a file, which contains host identifiers and tags. Unlike the host files that you use with streamtool addhost and mkinstance commands, this host file cannot contain --numresources specifications.

A host identifier can be a host name or IP address. Each host identifier must be on a separate line in the file.

The file can also contain comment lines (blank lines or lines where the first non-whitespace character is a '#').

For example:

host1,management

1.3.45.6,audit,authentication

Each host must have access to the Streams product. For more information about the considerations for setting up a multiple-host environment for Streams, see the product documentation.

--iam
Specifies whether IBM Identity and Access Management (IAM) authentication is enabled.
--iam-authz-endpoint-url <url>
Specifies the URL of the endpoint that is used to authenticate and authorize users when IBM Identity and Access Management (IAM) authentication is used.
--iam-client-id <client-id>
Specifies the IBM Identity and Access Management (IAM) client ID.
--iam-client-secret <client-secret>
Specifies the IBM Identity and Access Management (IAM) client secret.
--iam-jwks-endpoint-url <url>
Specifies the URL of the JSON Web Key Set (JWKS) endpoint that is used to verify the digital signatures of IBM Identity and Access Management (IAM) tokens.
--iam-logout-endpoint-url <url>
Specifies the URL of the endpoint that is used to handle IBM Identity and Access Management (IAM) logout requests.
--iam-token-endpoint-url <url>
Specifies the URL of the endpoint that is used to obtain IBM Identity and Access Management (IAM) tokens.
--ldap
Specifies to use LDAP to authenticate users. By default, domains use Pluggable Authentication Module (PAM).
--owner <owner>
Specifies the LDAP user ID that owns the domain. The command assigns the DomainAdministrator role to this user.
--property <name=value>
Specifies a property name and value pair to add to or change in the configuration. This option can be specified multiple times and has an additive effect.
--propfile <property-file>
Specifies the path for a file that contains a list of domain properties and command options, each on a separate line. You can specify:
  • Command options and their values. For example: admin-grp=myGrp
    • You must use the long version of the command option. For example, use verbose instead of v.
    • If the list includes domain-id or zkconnect options, they are ignored.
    • Options that you specify at the command line override values that were specified in this property file.
  • Domain properties and their values. For example: property.1=sws.port=0. The property statements must each have a unique number. For a list of domain properties, see streamtool man domainproperties.
If the command options or values are invalid, or are not relevant to this command, they are ignored. If the properties are instance or boot properties or they are domain properties but have invalid values, the command fails.
--server-url <url>
Specifies the URL for the LDAP server that the domain uses to authenticate users.
--trace <level>
Specifies the trace setting. The following valid levels are listed in order of increasing verbosity, which is to say that the first level in the list generates the least amount of information:
  • off
  • error
  • warn
  • info
  • debug
  • trace
The default value is off.
--user-attr <element-name>
Specifies the name of the element in a user record that is stored in the group record in LDAP.

If you specified:

  • --group-objgroupOfNames or groupOfUniqueNames, this option defaults to a value of dn.
  • --group-obj posixGroup, this option defaults to uid.
Consult your LDAP administrator for the correct value.
--user-dn <dn-pattern>
Specifies the LDAP pattern that is used to create a DN when the user logs in. For example: "cn=*,ou=People,ou=streams,o=ibm.com". When the user logs in, their user ID is substituted for the "*" in the pattern.
--user-grp <group>
Specifies a group whose members can use the domain. This group is added to the DomainUser role. If this option is not specified, only the following users can use the domain:
  • Users that have the DomainUser role.
  • The user that ran the streamtool mkdomain command, or the user that is specified in the --owner option.
--user-secondary-lookup <element-name>
Specifies an LDAP user secondary lookup query. Streams uses the query to determine the LDAP user name for the user that you specified when you ran the command or started the streamtool interactive session. For example: "(&(objectclass=person)(uidNumber=*)) uid".
-v,--verbose <level>
Specifies to provide more detailed command output. The verbosity level can be 0-3, where 0 disables detailed reporting and each increment provides more detailed output.
--zkconnect <{<host>:<port>},...>

The name of one or more host and port pairs that specify the configured ZooKeeper servers. This option is not supported within the interactive streamtool interface.

If you are not using the interactive streamtool interface and you do not specify this option, Streams tries to use:

  1. The --embeddedzk option
  2. The value from the STREAMS_ZKCONNECT environment variable
  3. A ZooKeeper connection string that is derived from cached information about the current domain.

Examples

The following example creates a domain with default values in the interactive streamtool interface:

[streamtool <?>] mkdomain
Domain ID: mydomain
CDISA0017I Creating domain mydomain.
CDISA0018I Domain mydomain creating successfully.
[streamtool <?@mydomain>]