U-Series Appliance Web Services

This portion of the guide details the U-Series Appliance web services (also referred to as endpoints). There are two endpoints in the U-Series Appliance: one to run the configuration, and one to monitor progress.

POST

/ApplianceGateway/api/BaseProductLicense/setwindowslicense

Endpoint to set Windows license.

POST

/ApplianceGateway/api/BaseProductLicense/skippage

Endpoint to skip Windows license page.

POST

/ApplianceGateway/api/DeploymentWizardAutomation

Endpoint to programmatically execute the deployment wizard.

GET

/ApplianceGateway/api/DeploymentWizardAutomation

Endpoint to get the status of the deployment wizard step execution. This is intended to be used after the Post in this controller has been called, to be able to poll the status as the steps are executed.

Status Code	Description
0	Not Started
1	In Progress
2	Passed
3	Paused
4	Failed

Sample Response Format

{
    "stepsStatus": [
        {
            "name": "Rename appliance",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Appliance renamed to automation"
            }
        },
        {
            "name": "Reboot appliance",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Reboot requested"
            }
        },
        {
            "name": "Pause the wizard while waiting for a reboot",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Pausing for reboot"
            }
        },
        {
            "name": "Create BeyondInsight EMS certificate",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Created the BeyondInsight EMS certificate"
            }
        },
        {
            "name": "Apply internet connection settings",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Internet connection settings applied"
            }
        },
        {
            "name": "Apply IP settings",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "IP settings applied"
            }
        },
        {
            "name": "Generate unique BeyondInsight cryptokey",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Generated unique BeyondInsight cryptokey"
            }
        },
        {
            "name": "Apply time settings",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Applied time settings"
            }
        }
    ],
    "overAllStatus": 2
}

POST

/ApplianceGateway/api/ConfigurationWizardAutomation

Endpoint to programmatically execute the configuration wizard.

GET

/ApplianceGateway/api/ConfigurationWizardAutomation

Endpoint to get the status of the configuration wizard step execution. This is intended to be used after the Post in this controller has been called, to be able to poll the status as the steps are executed.

Status Code	Description
0	Not Started
1	In Progress
2	Passed
3	Paused
4	Failed

Sample Response Format

{
    "stepsStatus": [
        {
            "name": "Apply License Settings",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "License settings applied"
            }
        },
        {
            "name": "Prepare local BeyondInsight Database",
            "outcomeInfo": {
                "stepStatus": 3,
                "stepOutcomeMessage": "Error encountered while preparing local BeyondInsight database ()"
            }
        },
        {
            "name": "Apply Backup Settings",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Backup settings applied"
            }
        },
        {
            "name": "Apply BeyondInsight Credentials",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "BeyondInsight Credentials applied"
            }
        },
        {
            "name": "Apply Central Policy password",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Central Policy password applied"
            }
        },
        {
            "name": "Apply Updater Credentials",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Updater Credentials applied"
            }
        },
        {
            "name": "Apply Updater Settings",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "Updater settings applied"
            }
        },
        {
            "name": "Apply PowerBroker for Windows",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "PowerBroker for Windows applied"
            }
        },
        {
            "name": "Apply SSL Certificate Settings",
            "outcomeInfo": {
                "stepStatus": 2,
                "stepOutcomeMessage": "SSL certificate applied"
            }
        },
        {
            "name": "Apply Roles",
            "outcomeInfo": {
                "stepStatus": 1,
                "stepOutcomeMessage": ""
            }
        }
    ],
    "overAllStatus": 1
}

GET

/UVMInterface/api/UVMConfiguration/IsApplianceConfigured

Endpoint to get the status of the appliance configuration.

Status Code	Description
0	Not Configured
1	Configured

Once complete, the configuration and deployment end points will be removed, and if the deployment or configuration is called, a 502 will be returned by the gateway.

GET

/ApplianceGateway/api/ApplianceInfoAutomation

Endpoint to get the network details.

Sample Response Format

{
    "ipSettings": [
        {
            "networkAdapter": " networkAdapter ",
            "networkCardId": "0",
            "useDhcp": true,
            "macAddress": null,
            "domainIp": "XX.XXX.XX.XXX",
            "subnetMask": "XXX.XXX.XXX.X",
            "defaultGateway": "XX.XXX.XX.X",
            "preferredDnsServer": "XX.XXX.X.XX",
            "alternateDnsServer": "XX.XXX.X.XX",
            "dnsSuffix": " dnsSuffix ",
            "modifiedSetting": false
        }
    ]
}

Prerequisite Before Deployment

Run Set Windows license or Skip License Page endpoint as Windows is not licensed.

Set Windows License

Route

/ApplianceGateway/api/BaseProductLicense/setwindowslicense

Windows key JSON will be sent to the web service.

Sample JSON format

{
    "key": "XXXXX- XXXXX - XXXXX - XXXXX - XXXXX "
}

Skip Windows License Page

Route

/ApplianceGateway/api/BaseProductLicense/skippage

Empty JSON will be sent to the web service.

Deployment Wizard

Route

/ApplianceGateway/api/DeploymentWizardAutomation

A valid BeyondInsight license key must be passed through a HTTP header

The Deployment JSON will be sent to the web service and will include:

Windows User credentials
Licensing Agreements
Appliance Name
IP Settings
Internet Connection Settings
Time zone and Time Settings
SMTP Settings

Sample JSON Format

{
  "configureUser": {
    "username": "btadmin",
    "password": "password",
    "email": "dummy@domain.com"
  },
  "licenseAgreement": {
    "acceptBtEula": true,
    "acceptMsEula": true,
    "acceptSqlServerEula": true
  },
  "applianceName": {
    "applianceName": "applianceName"
  },
  "ipSettings": [
    {
      "networkAdapter": "networkAdapter",
      "networkCardId": "",
      "useDhcp": true,
      "macAddress": "",
      "domainIp": "XX.XXX.XX.XXX",
      "subnetMask": "XXX.XXX.XXX.X",
      "defaultGateway": "XX.XXX.XX.X",
      "preferredDnsServer": "XX.XXX.X.XX",
      "alternateDnsServer": "XX.XXX.X.XX",
      "dnsSuffix": "dnsSuffix",
      "modifiedSetting": false
    }
  ],
  "internetConnectionSettings": {
    "connectThroughProxy": true,
    "proxySetting": {
      "proxyAddress": "XX.XXX.XX.XXX",
      "proxyPort": 808,
      "proxyUsername": "",
      "proxyPassword": ""
    }
  },
  "timeSettings": {
    "syncType": 0,
    "ntpServer": "ntpServer",
    "timezone": "Central Standard Time"
  },
  "smtpSettingsDto": {
    "emailServer": "emailServer",
    "smtpPort": 25,
    "ssl": true,
    "requiresAuthentication": false,
    "username": "username",
    "password": "password"
  }
}

Configuration Wizard

Route

/ApplianceGateway/api/ConfigurationWizardAutomation

A valid BeyondInsight license key must be passed through a HTTP header.

The Configuration JSON will be sent to the web service and will include:

BeyondTrust Licenses
Solution & Roles
User Credentials
Roles Configuration
Backup And Restore
Update Method

Sample JSON Format

{
  "license": {
    "licenseMode": 0,
    "serialNumber": "",
    "licenseKey": ""
  },
  "rolesSelected": {
    "sqlServerRole": true,
    "analysisServerRole": true,
    "sqlServerReportingServicesRole": true,
    "beyondInsightDatabaseAccess": true,
    "beyondInsightManagementConsole": true,
    "omniworkerRole": true,
    "eventCollectorRole": true,
    "passwordSafeConsoleRole": true,
    "biulSetupRole": false,
    "discoveryScannerRole": true
  },
  "credentials": {
    "biUserName": "btadmin",
    "biUserPassword": "password",
    "cpPassword": "password",
    "btUpdaterName": "btadmin",
    "btUpdaterPassword": "password",
    "biulUsername": "btadmin",
    "biulPassword": "password"
  },
  "roleConfigurationBiul": {
    "biulIsRemote": true,
    "biulServerName": "XX.XXX.XXX.XX",
    "biulSqlUser": "username",
    "biulSqlPassword": "password",
    "biulDatabaseName": "PBSMC",
    "biulPort": 0,
    "biulDbInstance": "InstanceName"
  },
  "roleConfigurationRemoteSql": {
    "biIncomingDatabasePassword": "password",
    "allowIncomingDatabaseConnections": false
  },
  "roleConfigurationSqlAccess": {
    "biConnectionServerName": "ServerName",
    "biConnectionDatabaseName": "RetinaCsDatabase",
    "biCommandTimeout": 300,
    "biConnectionTimeout": 60,
    "biDatabaseConnectionStringUsername": "beyondtrust_user",
    "biDatabaseConnectionStringUserPassword": "password",
    "biDatabaseConnectionStringMultiSubnetFailover": false,
    "biCreateRemoteDatabase": false,
    "biDatabaseIsLocal": true,
    "biAdministratorUsername": "btadmin",
    "biAdministratorPassword": "password"
  },
  "backupRestore": {
    "backupOption": 1,
    "backupSetting": {
      "path": "path",
      "username": "",
      "password": "",
      "domain": "",
      "startTime": "2021-07-19T18:55:51.522Z",
      "frequency": 0,
      "backupPassword": "password"
    }
  },
  "updates": {
    "updatesOption": 0,
    "serverAddress": "ServerAddress"
  }
}