Register SDC Edge

You must register each Data Collector Edge (SDC Edge) to work with Control Hub. You can register Edge Data Collectors from Control Hub or from the SDC Edge command line interface.

Note: If you download SDC Edge from Control Hub, you can automatically register the SDC Edge with Control Hub during the installation. If you use another installation method, you'll need to manually register the SDC Edge with Control Hub after the installation.
You generate an authentication token for each registered SDC Edge. SDC Edge uses the authentication token to issue requests to Control Hub. Because all communication between Control Hub and a registered SDC Edge uses HTTPS, the authentication token is kept confidential.

A registered SDC Edge communicates with Control Hub at regular intervals. If an SDC Edge cannot connect to Control Hub, due to a network or system outage, then the SDC Edge uses the Control Hub disconnected mode.

For more details about how Control Hub and SDC Edge work together, see SDC Edge Communication.

Registering from Control Hub

When you register SDC Edge from Control Hub, you use Control Hub to generate an authentication token and then modify the SDC Edge configuration file.

  1. In the Navigation panel, click Administration > Edge Data Collectors.
    Control Hub displays any SDC Edge that has already been registered.
  2. Click the Generate Authentication Tokens icon: .
  3. Enter the number of tokens to generate.
  4. Click Generate.
    The Authentication Tokens window displays each generated token.
  5. Record the generated tokens.
    You can copy the tokens from the window. Or, you can click Download to download all generated tokens to a JSON file named authTokens.json.
    Note: If you close the window before recording the tokens, you cannot retrieve the tokens. You can delete unregistered authentication tokens, as described in Deleting Unregistered Tokens.
  6. Click Close in the Authentication Tokens window.
  7. Complete the following steps for each SDC Edge that you want to register:
    1. Open the <SDCEdge_home>/etc/edge.conf file for the SDC Edge, and paste a token into the app-auth-token property in the file.
      Each SDC Edge must use a unique authentication token.
    2. Edit the following Control Hub properties in the <SDCEdge_home>/etc/edge.conf file:
      Control Hub Property Description
      enabled Set to true.
      base.url

      Set to https://cloud.streamsets.com.
    3. Restart the SDC Edge.

Registering from the Command Line Interface

When you register SDC Edge from the command line interface, the command generates the authentication token and modifies the SDC Edge configuration file for you.

You can register SDC Edge from the command line using a Control Hub password or using a Control Hub user authentication token.

Registering with a Password

You can use the SDC Edge command line interface to register SDC Edge with Control Hub using your Control Hub user name and password.

Run the following command from the SDC Edge home directory:
bin/edge -enableControlHub -controlHubUrl=<Control Hub URL> -controlHubUser=<user name> -controlHubPassword=<password> -controlHubLabels=<labels>
For example, the following command registers SDC Edge with the MyCompany organization in Control Hub cloud, assigning two labels to the SDC Edge:
bin/edge -enableControlHub -controlHubUrl=https://cloud.streamsets.com -controlHubUser=admin@MyCompany -controlHubPassword=MyPassword -controlHubLabels=Production,East

After running the command, restart SDC Edge to complete the registration process.

Registering with a User Authentication Token

To avoid exposing your Control Hub password, you can use the Control Hub REST API to log into the Control Hub security application and generate a user authentication token for your user account. Then use the SDC Edge command line interface to register SDC Edge with Control Hub using this user authentication token.

You might want to use a user authentication token when you need to register multiple Edge Data Collectors running on remote edge devices. You can send the user authentication token to the remote edge devices instead of sending your password.

When you generate a user authentication token, the token is valid for 24 hours. If desired, you can run a command to invalidate the token immediately after using it.

  1. Run the following command to log into the Control Hub security application and store the generated user authentication token in a temporary text file: 
    curl -X POST -d '{"userName":"<user name>", "password": "<password>"}' <Control Hub URL>/security/public-rest/v1/authentication/login --header "Content-Type:application/json" --header "X-Requested-By:SDC" -c <text file>

    For example, the following command logs into Control Hub cloud as the admin user of the MyCompany organization and stores the user authentication token in a file named cookie.txt:

    curl -X POST -d '{"userName":"admin@MyCompany", "password": "MyPassword"}' https://cloud.streamsets.com/security/public-rest/v1/authentication/login --header "Content-Type:application/json" --header "X-Requested-By:SDC" -c cookie.txt
  2. Run the following command to read the user authentication token from the temporary text file and assign it to a local environment variable named sessionToken: 
    sessionToken=$(cat cookie.txt | grep SSO | rev | grep -o '^\S*' | rev)
  3. Run the following command to display the user authentication token in the command prompt: 
    echo "Generated session token : $sessionToken"
  4. Copy the user authentication token.
  5. Run the following command from the SDC Edge home directory to use the token to register SDC Edge with Control Hub: 
    bin/edge -enableControlHub -controlHubUrl=<Control Hub URL> -controlHubUser=<user name> -controlHubUserToken=<token> -controlHubLabels=<labels>
    For example, the following command registers SDC Edge with the MyCompany organization in Control Hub cloud, assigning two labels to the SDC Edge:
    bin/edge -enableControlHub -controlHubUrl=https://cloud.streamsets.com -controlHubUser=admin@MyCompany -controlHubUserToken=d2bab2b3-2a1e-4368-9b18-23cdb9c2d97e|-1542046203506 -controlHubLabels=Production,East
  6. Restart SDC Edge to complete the registration process.
  7. Optionally invalidate the user authentication token.
    Control Hub invalidates each user authentication token after 24 hours. If desired, you can run a command to invalidate the token immediately after using it to register SDC Edge.
    Run the following command to invalidate the token:
    curl -X POST <Control Hub URL>/security/_logout --header "Content-Type:application/json" --header "X-Requested-By:SDC" --header "X-SS-REST-CALL:true" --header "X-SS-User-Auth-Token:$sessionToken" -i
    For example, the following command invalidates the user authentication token in Control Hub cloud:
    curl -X POST https://cloud.streamsets.com/security/_logout --header "Content-Type:application/json" --header "X-Requested-By:SDC" --header "X-SS-REST-CALL:true" --header "X-SS-User-Auth-Token:$sessionToken" -i

enableControlHub Command Line Options

Use the -enableControlHub command to register SDC Edge. SDC Edge does not need to be running to use the command.

Use the command from the SDC Edge home directory as follows:
bin/edge -enableControlHub \
(-controlHubUrl <Control Hub URL>) \
(-controlHubUser <Control Hub user>) \
[(-controlHubPassword <password>)] \
[(-controlHubUserToken <user token>)] \
[(-controlHubLabels <labels>)]
The following table describes the -enableControlHub options:
enableControlHub Option Description
-controlHubUrl <Control Hub URL> Required. URL to access Control Hub.

Set to https://cloud.streamsets.com.
-controlHubUser <Control Hub user> Required. Enter your Control Hub user ID using the following format:
<ID>@<organization ID>
-controlHubPassword <password> Required when registering with a password. Enter the password for your Control Hub user account.

Do not use with the -controlHubUserToken option.
-controlHubUserToken <user token> Required when registering with a user authentication token. Enter the user authentication token generated for your Control Hub user account.

Do not use with the -controlHubPassword option.
-controlHubLabels <labels> Optional. Assign a label to this SDC Edge. You can enter multiple labels separated by commas. Labels that you assign here are defined in the SDC Edge configuration file, <SDCEdge_home>/etc/edge.conf. To remove these labels after you register the SDC Edge, you must modify the configuration file.

Use labels to group Edge Data Collectors registered with Control Hub. If you know how you want to group your Edge Data Collectors, you can assign labels now. Or you can assign labels in Control Hub after you register SDC Edge.

Default is "all", which you can use to run a job on all registered Edge Data Collectors.

Deleting Unregistered Tokens

Delete unregistered authentication tokens when you used Control Hub to generate the tokens, but did not copy or download the tokens from the Generate Authentication Token window.

Control Hub lists the number of unregistered authentication tokens in the Data Collector Edge Administration view as follows:

  1. In the Navigation panel, click Administration > Edge Data Collectors.
  2. Click the Toggle Filter Column icon () to view the number of unregistered authentication tokens.
  3. Click the More icon , and then click Delete Unregistered Authentication Tokens.

Deactivating a Registered SDC Edge

Deactivate a registered SDC Edge when you want to temporarily prevent users from using that SDC Edge.

When you deactivate an SDC Edge, Control Hub deactivates the authentication token for the SDC Edge. Shut down the SDC Edge before you deactivate it. You cannot start a deactivated SDC Edge.

  1. In Control Hub, stop all jobs running on the SDC Edge.
  2. Shut down the SDC Edge on the edge device by typing Ctrl+C in the command prompt.
  3. In Control Hub, click Administration > Edge Data Collectors in the Navigation panel.
  4. Select a registered SDC Edge to display its details.
  5. Click Deactivate.
    The Data Collector Edge Administration view uses a gray SDC Edge icon for any deactivated SDC Edge, as follows:

  6. To activate the SDC Edge again, view the SDC Edge details in Control Hub and click Activate. Then, start the SDC Edge.

Regenerating a Token

You can regenerate an authentication token for an SDC Edge. You might need to regenerate a token to replace a token that has been compromised or to follow your organization's security policy.

When you regenerate an authentication token for an SDC Edge, you replace the previous authentication token with a new one. You must copy the new token into the <SDCEdge_home>/etc/edge.conf file for the SDC Edge.

  1. In the Navigation panel, click Administration > Edge Data Collectors.
  2. Select a registered SDC Edge to display its details.
  3. Click Regenerate Authentication Token.
    The Authentication Tokens window displays the regenerated token.
  4. Record the regenerated token.
    You can copy the token from the window. Or, you can click Download to download the token to a JSON file named authTokens.json.
    Note: If you close the window before recording the token, you cannot retrieve the token. You can delete unregistered authentication tokens, as described in Deleting Unregistered Tokens.
  5. To register the SDC Edge with the newly generated token, copy the token to the app-auth-token property in the <SDCEdge_home>/etc/edge.conf file and restart the SDC Edge.

Disabling SDC Edge from Working with Control Hub

Use the SDC Edge command line interface to temporarily disable an SDC Edge installation from working with Control Hub. SDC Edge does not need to be running to use the command.

Important: Using the SDC Edge command line interface does not completely unregister SDC Edge from Control Hub. To completely unregister SDC Edge, use Control Hub.
Run the following command from the SDC Edge home directory to temporarily disable SDC Edge from working with Control Hub:
bin/edge -disableControlHub

The command sets the enabled property to false in the SDC Edge configuration file, <SDCEdge_home>/etc/edge.conf.

To enable SDC Edge to work with Control Hub again, simply set the enabled property to true in the edge.conf file.

Unregistering an SDC Edge

You can unregister an SDC Edge from Control Hub when you no longer want to use that SDC Edge installation with Control Hub.

When you unregister an SDC Edge from Control Hub, Control Hub deactivates the authentication token. If you want to locally run the SDC Edge on the edge device, modify the SDC Edge configuration file to remove the authentication token and to disable communication with Control Hub.

  1. In Control Hub, stop all jobs running on the SDC Edge.
  2. Shut down the SDC Edge on the edge device.
  3. In Control Hub, click Execute > Edge Data Collectors in the Navigation panel.
  4. Hover over the SDC Edge that you shut down, and then click the Delete icon.
  5. In the confirmation dialog box, click Delete and Unregister.
  6. On the edge device where the SDC Edge is installed, open the <SDCEdge_home>/etc/edge.conf file, and make the following changes:
    • Set the enabled property to false.
    • Remove the authentication token from the app-auth-token property.