Creating an enterprise domain by using the Teracloud® Streams streamtool command-line interface

Use this procedure to create an enterprise domain by using the Teracloud® Streams streamtool mkdomain command.

Procedure

To set the Teracloud® Streams ZooKeeper connection string in an environment variable, enter the following command. This setting eliminates the need to specify the connection string on subsequent commands.
```
  export STREAMS_ZKCONNECT=external-ZooKeeper-connection-string
```
For example:
```
  export STREAMS_ZKCONNECT=192.168.1.100:2181,192.168.1.101:2182,192.168.1.103:2183
```
To configure your local shell environment for Teracloud® Streams, enter the following command:
```
  source product-installation-root-directory/7.2.0.0/bin/streamsprofile.sh
```
To complete this procedure in the interactive streamtool interface, enter the following command:
```
    streamtool  
```
Using the interactive streamtool interface saves you time. Teracloud® Streams caches some command options and information so that you do not have to reenter them. Also, you do not have to specify streamtool before each command. To exit the interactive streamtool interface, enter exit or quit.
Create an enterprise domain by using the streamtool mkdomain command.
- To create an enterprise domain that uses PAM for user authentication, enter the following command:
```
mkdomain -d domain-id --property domain.highAvailabilityCount=number   
```
  Notes:
  - To configure high availability in Teracloud® Streams enterprise domains, you must specify a domain.highAvailabilityCount domain property value greater than 1. For more information, see Configuring high availability for Teracloud Streams enterprise domains, instances, and application repositories.
- To create an enterprise domain that uses LDAP for user authentication, enter the following command. When prompted, enter the LDAP password for the domain owner.
```
mkdomain -d domain-id --ldap --server-url URL --user-dn DN-pattern --property domain.highAvailabilityCount=number   
```
  For example:
```
mkdomain -d StreamsDomain --ldap --server-url ldap://ldap.streams.com:389 --user-dn uid=*,ou=people,dc=streams,dc=com --property domain.highAvailabilityCount=3   
```
  Notes:
  - The owner of the domain is the user who runs the command by default. To specify another owner, use the following command options:
    --owner LDAP-user-ID
    If you specify another owner, enter the LDAP password of that owner when prompted. Otherwise, enter the LDAP password of the user who is running the command. The password prompt tells you which user is the owner. For example, if you specify --owner tester1 on the command but tester3 is creating the domain, the password prompt says User tester1 LDAP password.
  - To configure high availability in Teracloud® Streams enterprise domains, you must specify a domain.highAvailabilityCount domain property value greater than 1. For more information, see Configuring high availability for Teracloud Streams enterprise domains, instances, and application repositories.
To display the resources in the domain, enter the following command:
```
  lsavailablehosts
```
As shown in the following example, there is one resource in the domain. You assign tags to this resource later in this procedure.
```
Resource                       Tags
myhost1.ibm.com
```
Optional: Set up automatic recovery from failures on this resource.
For high availability with automatic recovery from failures, the domain controller service must run as a registered Linux system service on this resource. You can set up the controller on additional resources when you add those resources to the domain.
To set up the controller as a system service on this resource, enter the following command:
```
streamtool registerdomainhost -d domain-id --zkconnect host:port
```
- You must have root authority to run this command.
- The --zkconnect option specifies the name of one or more host and port pairs for the configured external ZooKeeper ensemble. If you specify multiple host and port pairs, separate each pair with a comma. This value is the external ZooKeeper connection string. To obtain this value, you can use the streamtool getzk command.
Optional: Change the default location for Teracloud® Streams log and trace files.
The default root directory for class cache, log, and trace files that are generated by Teracloud® Streams is the /tmp directory. If you use a system maintenance utility such as tmpwatch, either modify the utility to exclude these files or configure a different root directory by using the following Teracloud® Streams domain properties:
- domain.fileStoragePath: This property specifies the root directory where Teracloud® Streams class cache and other temporary files are stored. If the class cache files are removed, the web management service might fail and not recover correctly.
- domainLog.path: This property specifies the root directory where Teracloud® Streams log and trace files are stored. If these files are removed, it might be difficult to resolve Teracloud® Streams problems.
You can update these properties by using the streamtool setdomainproperty command.
Set up additional resources in the domain.
Complete the following steps after you set up the resources in the domain:
1. Verify that the resources are added to the domain.
  For example, you can use the streamtool lsavailablehosts command. The following command output example shows a domain that includes three Teracloud® Streams resources.
```
Resource                          Tags
myhost1.ibm.com
myhost2.ibm.com
myhost3.ibm.com
```
2. Assign management and application tags to the resources.
  Assign at least two resources as management resources and the other resources as application resources. Tag names are case-sensitive.
  For example, the following commands assign the management tag to host1 and host2, and the application tag to host3:
```
chhost --tags management host1,host2
chhost --tags application host3
```
  For more information, see Assigning tags to resources in a domain.
Start the domain by entering the following command:
```
  startdomain
```
When prompted, enter your domain ID and password. If another domain owner was specified on the mkdomain command, enter the ID and password of the owner.
Tip: If the domain fails to start because a port is in use, you can change the port number by using the streamtool setdomainproperty command. For example, if the domain fails to start because one or more of the JMX management API service, web management service, and REST management API service ports are in use, you can enter the following command. If you specify a value of 0 for the port number, Teracloud® Streams selects an available port.
```
setdomainproperty jmx.port=0 sws.port=0 rest.port=0
```
Dynamic port allocation is not ideal, however, if you have applications that use the REST API or JMX API or use tools (such as Streams Console) that access those services.
Create one or more instances for running stream applications.
To manage and monitor the domain, you can use the Streams Console. The domain must be started to use the console.
To open the console:
1. Enter geturl to display the URL for the console. For example, if your resource is myhost.mydomain.com and the port number for the console is 8440, this command displays the following URL:
```
https://myhost.mydomain.com:8440/streams/domain/console
```
2. Paste this URL into your browser.
To exit the interactive streamtool interface, enter exit or quit.