# Configure Services

These are a collection of endpoints that allow you to configure Birds that are connected to your Console.

# Configure Bird

TIP

The Configure Bird with Personality endpoint allows for an easier configuration process, especially if you are simply wanting to use an existing personality.

POST /api/v1/device/configure

Configure a Bird with a specified JSON settings object

Required Parameters

auth_token string
A valid auth token
node_id string
A valid Canary node_id
settings string
A serialized JSON object of the Bird settings

Settings Object

The settings object currently requires you to provide a full, valid settings object that conforms to our settings object.

Optional Parameters

custom_personality_name string
Custom personality name to save this config under

Custom Personality Name

Providing custom_personality_name allows you to save the provided settings object as a custom personality. This lets you reuse the settings object easily for further Bird configurations.

Response

JSON structure with result and bundle_tag if successful.

Example

    Response
    {
      "bundle_tag": "<bundle_tag>",
      "custom_personality_name": null,
      "msg": "All properties are expected.",
      "result": "success"
    }
    
    1
    2
    3
    4
    5
    6

    # Configure Bird with Personality

    POST /api/v1/device/configure_personality

    Configure a Bird with a supplied personality.

    Required Parameters

    auth_token string
    A valid auth token
    node_id string
    A valid Canary node_id
    personality string
    A valid personality from the Canary schema or custom saved personality

    Personality

    A list of available personalities can be obtained by calling the List Personalities endpoint.

    Optional Parameters

    additional_settings string
    A serialized json object of additional Bird settings

    Response

    JSON structure with result and bundle_tag if successful.

    Example

    A simple example of pushing the osx-fileshare personality to a Bird:

      Response
      {
        "bundle_tag": "<bundle_tag>",
        "msg": "All properties are expected.",
        "result": "success"
      }
      
      1
      2
      3
      4
      5

      # Share Upload

      Although we allow for uploading and pushing files through the Configure Bird endpoint, it is size-constrained as pushing large files over DNS isn't ideal (and takes a considerable amount of time.).

      To get around this, you can remotely enable Share Upload on a Bird (from version 2.2 onwards). This temporarily enables a writable share on the Bird that you can connect to over the network and upload files to.

      # Check Share Upload Status

      GET /api/v1/shareupload/status

      Check the status of a Bird's share upload.

      Required Parameters

      auth_token string
      A valid auth token
      node_id string
      A valid Canary node_id

      Response

      A JSON structure with the current share upload status.

      Example

        Response
        {
          "job_id": "<job_id>",
          "password": "<password>",
          "pid": "691",
          "result": "progress",
          "type": "Start"
        }
        
        1
        2
        3
        4
        5
        6
        7

        # End Share Upload

        POST /api/v1/shareupload/end

        End and save the share upload on a Bird.

        Required Parameters

        auth_token string
        A valid auth token
        node_id string
        A valid Canary node_id

        Optional Parameters

        cancel boolean
        Ignore changes made to the writable upload share when parameter is present

        Response

        A JSON structure with result indicator.

        Example

          Response
          {
            "job_id": "<job_id>",
            "password": "<password>",
            "pid": "691",
            "result": "progress",
            "type": "RequestEnd"
          }
          
          1
          2
          3
          4
          5
          6
          7

          # Start Share Upload

          POST /api/v1/shareupload/start

          Start a share upload for a Bird.

          Required Parameters

          auth_token string
          A valid auth token
          node_id string
          A valid Canary node_id

          Response

          A JSON structure with result indicator.

          Example

            Response
            {
              "job_id": "<job_id>",
              "password": "<password>",
              "result": "progress",
              "type": "RequestStart"
            }
            
            1
            2
            3
            4
            5
            6

            # Webroot Upload

            Using the Configure Bird endpoint, you are able to select a pre-defined site to expose on your HTTP service. These pre-defined webroots are useful and mimic a multitude of existing systems that you'd expect to find on a network.

            However, if you'd like to expose your own site, we allow you to upload your own custom webroot to your Birds (from version 2.2 onwards). In order to do this, you can enable a temporary endpoint on your Bird that will allow you to access it over the network, and upload a zip containing your site.

            TIP

            For details about how the zip should be structured, you can look at our help article (opens new window).

            # Check Webroot Upload Status

            GET /api/v1/webrootupload/status

            Check the status of a Bird's webroot upload.

            Required Parameters

            auth_token string
            A valid auth token
            node_id string
            A valid Canary node_id

            Response

            A JSON structure with the current webroot upload status.

            Example

              Response
              {
                "result": "progress",
                "type": "RequestStart"
              }
              
              1
              2
              3
              4

              # End Webroot Upload

              POST /api/v1/webrootupload/end

              Cancel the webroot upload for a Bird.

              Required Parameters

              auth_token string
              A valid auth token
              node_id string
              A valid Canary node_id

              Response

              A JSON structure with result indicator.

              Example

                Response
                {
                  "result": "progress",
                  "type": "RequestCancel"
                }
                
                1
                2
                3
                4

                # Start Webroot Upload

                POST /api/v1/webrootupload/start

                Start a webroot upload for a Bird.

                Required Parameters

                auth_token string
                A valid auth token
                node_id string
                A valid Canary node_id

                Response

                A JSON structure with result indicator.

                Example

                  Response
                  {
                    "result": "progress",
                    "type": "RequestStart"
                  }
                  
                  1
                  2
                  3
                  4

                  # Settings Object

                  Whenever providing a serialized JSON Bird settings object, you'll need to ensure that it contains the full Bird settings (this includes settings that you do not change.)

                  The easiest way to achieve this is to call the Bird Info endpoint with settings=true and alter the returned settings object as you need.

                  We've provided a full example bare-canary Bird settings object for you to inspect.

                  Response
                  "settings": {
                    "device.ad_pubkey": "<ad_pubkey>",
                    "device.desc": "SVR Room",
                    "device.dhcp.enabled": true,
                    "device.dns1": "192.168.0.1",
                    "device.dns2": "192.168.0.2",
                    "device.gw": "192.168.0.1",
                    "device.ip_address": "192.168.1.2",
                    "device.ippers": "win2012",
                    "device.mac": "00:00:00:00:00:00",
                    "device.name": "ExampleBird",
                    "device.netmask": "255.255.255.0",
                    "device.personality": "bare",
                    "device.usermodule": [],
                    "firewall.enabled": false,
                    "firewall.rulelist": [
                      {
                        "port": "null",
                        "rule": "",
                        "source": ""
                      }
                    ],
                    "ftp.banner": "FTP server ready",
                    "ftp.enabled": false,
                    "ftp.port": 21,
                    "git.enabled": false,
                    "git.port": 9418,
                    "http.banner": "Apache/2.2.22 (Ubuntu)",
                    "http.enabled": false,
                    "http.headers": {},
                    "http.headers.enabled": false,
                    "http.port": 80,
                    "http.skin": "nasLogin",
                    "http.userwebroot_present": false,
                    "httpproxy.banner": "",
                    "httpproxy.enabled": false,
                    "httpproxy.port": 8080,
                    "httpproxy.skin": "squid",
                    "https.enabled": false,
                    "https.headers": {},
                    "https.headers.enabled": false,
                    "https.redirect_http.enabled": false,
                    "modbus.enabled": false,
                    "modbus.majorminorrevision": "1.2",
                    "modbus.modelname": "",
                    "modbus.port": 502,
                    "modbus.productcode": "1",
                    "modbus.productname": "1769-L23E-QB1 Ethernet Port",
                    "modbus.userapplicationname": "device1",
                    "modbus.vendorname": "Rockwell Automation/Allen Bradley",
                    "modbus.vendorurl": "http://www.rockwellautomation.com",
                    "mssql.enabled": false,
                    "mssql.port": 1433,
                    "mssql.version": "2012",
                    "mysql.banner": "5.5.43-0ubuntu0.14.04.1",
                    "mysql.enabled": false,
                    "mysql.port": 3306,
                    "ntp.enabled": false,
                    "ntp.port": 123,
                    "portscan.enabled": false,
                    "redis.enabled": false,
                    "redis.port": 6379,
                    "remoteupdates.enabled": true,
                    "rollback.enabled": true,
                    "sip.enabled": false,
                    "sip.port": 5060,
                    "smb.advanced.enabled": false,
                    "smb.advanced.preferred_dc.enabled": false,
                    "smb.advanced.preferred_dc.servers": "",
                    "smb.advanced.serversigning": "mandatory",
                    "smb.domain": "corp.thinkst.com",
                    "smb.enabled": false,
                    "smb.filetree": [
                      {
                        "children": [
                          {
                            "name": "Default Cisco Router Config.docx",
                            "type": "docx"
                          },
                          {
                            "name": "Default Windows Desktop Configuration.docx",
                            "type": "docx"
                          },
                          {
                            "children": [
                              {
                                "name": "network_diagram_dmz.pdf",
                                "type": "pdf"
                              },
                              {
                                "name": "network_diagram_ldn_office.pdf",
                                "type": "pdf"
                              }
                            ],
                            "name": "network",
                            "type": "folder"
                          }
                        ],
                        "name": "IT",
                        "type": "folder"
                      },
                      {
                        "children": [
                          {
                            "name": "Executive Contact Details.docx",
                            "type": "docx"
                          },
                          {
                            "name": "NDA_template.docx",
                            "type": "docx"
                          },
                          {
                            "name": "Executive Compensation 2019-20.pdf",
                            "type": "pdf"
                          }
                        ],
                        "name": "Staff Docs",
                        "type": "folder"
                      }
                    ],
                    "smb.guest.enabled": true,
                    "smb.mode": "workgroup",
                    "smb.netbios_domain.enabled": false,
                    "smb.netbiosname": "OFFICESHARE",
                    "smb.serverstring": "Office Share",
                    "smb.sharecomment": "Office Document Share",
                    "smb.sharename": "Documents",
                    "smb.workgroup": "OFFICE",
                    "snmp.enabled": false,
                    "snmp.port": 161,
                    "ssh.enabled": false,
                    "ssh.port": 22,
                    "ssh.preauth_banner": "",
                    "ssh.version": "SSH-2.0-MS_1.100",
                    "tcpbanner.enabled": false,
                    "tcpbanner_1.alertstring": "",
                    "tcpbanner_1.alertstring.enabled": false,
                    "tcpbanner_1.datareceivedbanner": "502 5.5.2 Error: command not recognized\\r\\n",
                    "tcpbanner_1.enabled": false,
                    "tcpbanner_1.initbanner": "220 My Simple Fake SMTP Server.\\r\\n",
                    "tcpbanner_1.keep_alive.enabled": false,
                    "tcpbanner_1.keep_alive_secret": "",
                    "tcpbanner_1.port": 8001,
                    "tcpbanner_10.datareceivedbanner": "",
                    "tcpbanner_10.enabled": false,
                    "tcpbanner_10.initbanner": "",
                    "tcpbanner_10.port": 8010,
                    "tcpbanner_2.datareceivedbanner": "",
                    "tcpbanner_2.enabled": false,
                    "tcpbanner_2.initbanner": "",
                    "tcpbanner_2.port": 8002,
                    "tcpbanner_3.datareceivedbanner": "",
                    "tcpbanner_3.enabled": false,
                    "tcpbanner_3.initbanner": "",
                    "tcpbanner_3.port": 8003,
                    "tcpbanner_4.datareceivedbanner": "",
                    "tcpbanner_4.enabled": false,
                    "tcpbanner_4.initbanner": "",
                    "tcpbanner_4.port": 8004,
                    "tcpbanner_5.datareceivedbanner": "",
                    "tcpbanner_5.enabled": false,
                    "tcpbanner_5.initbanner": "",
                    "tcpbanner_5.port": 8005,
                    "tcpbanner_6.datareceivedbanner": "",
                    "tcpbanner_6.enabled": false,
                    "tcpbanner_6.initbanner": "",
                    "tcpbanner_6.port": 8006,
                    "tcpbanner_7.datareceivedbanner": "",
                    "tcpbanner_7.enabled": false,
                    "tcpbanner_7.initbanner": "",
                    "tcpbanner_7.port": 8007,
                    "tcpbanner_8.datareceivedbanner": "",
                    "tcpbanner_8.enabled": false,
                    "tcpbanner_8.initbanner": "",
                    "tcpbanner_8.port": 8008,
                    "tcpbanner_9.datareceivedbanner": "",
                    "tcpbanner_9.enabled": false,
                    "tcpbanner_9.initbanner": "",
                    "tcpbanner_9.port": 8009,
                    "telnet.authentication_failed_prompt": "\\nLogin incorrect\\n\\n",
                    "telnet.banner": "Welcome to Microsoft Telnet Service\\r\\n",
                    "telnet.enabled": false,
                    "telnet.password_prompt": "password: ",
                    "telnet.port": 23,
                    "telnet.user_prompt": "login: ",
                    "tftp.enabled": false,
                    "tftp.port": 69,
                    "vnc.enabled": false,
                    "vnc.port": 5900
                  }
                  
                  1
                  2
                  3
                  4
                  5
                  6
                  7
                  8
                  9
                  10
                  11
                  12
                  13
                  14
                  15
                  16
                  17
                  18
                  19
                  20
                  21
                  22
                  23
                  24
                  25
                  26
                  27
                  28
                  29
                  30
                  31
                  32
                  33
                  34
                  35
                  36
                  37
                  38
                  39
                  40
                  41
                  42
                  43
                  44
                  45
                  46
                  47
                  48
                  49
                  50
                  51
                  52
                  53
                  54
                  55
                  56
                  57
                  58
                  59
                  60
                  61
                  62
                  63
                  64
                  65
                  66
                  67
                  68
                  69
                  70
                  71
                  72
                  73
                  74
                  75
                  76
                  77
                  78
                  79
                  80
                  81
                  82
                  83
                  84
                  85
                  86
                  87
                  88
                  89
                  90
                  91
                  92
                  93
                  94
                  95
                  96
                  97
                  98
                  99
                  100
                  101
                  102
                  103
                  104
                  105
                  106
                  107
                  108
                  109
                  110
                  111
                  112
                  113
                  114
                  115
                  116
                  117
                  118
                  119
                  120
                  121
                  122
                  123
                  124
                  125
                  126
                  127
                  128
                  129
                  130
                  131
                  132
                  133
                  134
                  135
                  136
                  137
                  138
                  139
                  140
                  141
                  142
                  143
                  144
                  145
                  146
                  147
                  148
                  149
                  150
                  151
                  152
                  153
                  154
                  155
                  156
                  157
                  158
                  159
                  160
                  161
                  162
                  163
                  164
                  165
                  166
                  167
                  168
                  169
                  170
                  171
                  172
                  173
                  174
                  175
                  176
                  177
                  178
                  179
                  180
                  181
                  182
                  183
                  184
                  185
                  186
                  187
                  188
                  189
                  190