# 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.

curl https://EXAMPLE.canary.tools/api/v1/device/configure \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID \
  -d settings=EXAMPLE_SETTINGS_OBJECT
 
        Copied!

1
2
3
4

Response

{
  "bundle_tag": "<bundle_tag>",
  "custom_personality_name": null,
  "msg": "All properties are expected.",
  "result": "success"
}
 
        Copied!

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:

cURL
Python

curl https://EXAMPLE.canary.tools/api/v1/device/configure_personality \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID \
  -d personality=osx-fileshare
 
        Copied!

1
2
3
4

Response

{
  "bundle_tag": "<bundle_tag>",
  "msg": "All properties are expected.",
  "result": "success"
}
 
        Copied!

1
2
3
4
5

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.

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

cURL
Python

curl https://EXAMPLE.canary.tools/api/v1/shareupload/status \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID \
  -G
 
        Copied!

1
2
3
4

Response

{
  "job_id": "<job_id>",
  "password": "<password>",
  "pid": "691",
  "result": "progress",
  "type": "Start"
}
 
        Copied!

1
2
3
4
5
6
7

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

cURL
Python

curl https://EXAMPLE.canary.tools/api/v1/shareupload/end \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID 
 
        Copied!

1
2
3

Response

{
  "job_id": "<job_id>",
  "password": "<password>",
  "pid": "691",
  "result": "progress",
  "type": "RequestEnd"
}
 
        Copied!

1
2
3
4
5
6
7

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

cURL
Python

curl https://EXAMPLE.canary.tools/api/v1/shareupload/status \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID \
  -G
 
        Copied!

1
2
3
4

Response

{
  "job_id": "<job_id>",
  "password": "<password>",
  "result": "progress",
  "type": "RequestStart"
}
 
        Copied!

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

cURL
Python

curl https://EXAMPLE.canary.tools/api/v1/webrootupload/status \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID \
  -G
 
        Copied!

1
2
3
4

Response

{
  "result": "progress",
  "type": "RequestStart"
}
 
        Copied!

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

cURL
Python

curl https://EXAMPLE.canary.tools/api/v1/webrootupload/end \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID 
 
        Copied!

1
2
3

Response

{
  "result": "progress",
  "type": "RequestCancel"
}
 
        Copied!

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

cURL
Python

curl https://EXAMPLE.canary.tools/api/v1/webrootupload/start \
  -d auth_token=EXAMPLE_AUTH_TOKEN \
  -d node_id=EXAMPLE_NODE_ID 
 
        Copied!

1
2
3

Response

{
  "result": "progress",
  "type": "RequestStart"
}
 
        Copied!

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,
  "httpproxy.banner": "",
  "httpproxy.enabled": false,
  "httpproxy.port": 8080,
  "httpproxy.skin": "squid",
  "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,
  "services": {
    "http": {
      "enabled": false, 
      "instance_defaults": {}, 
      "instances": [
        {
          "banner": "Apache/2.2.22 (Ubuntu)", 
          "enabled": false, 
          "headers": {
            "enabled": false, 
            "items": {}
          }, 
          "name": "Default Webserver", 
          "port": 80, 
          "skin": "nasLogin"
        }
      ], 
      "userwebroot_present": false
    }, 
    "https": {
      "enabled": false, 
      "instance_defaults": {}, 
      "instances": [
        {
          "banner": "Apache/2.2.22 (Ubuntu)", 
          "enabled": false, 
          "headers": {
            "enabled": false, 
            "items": {}
          }, 
          "name": "Default Webserver", 
          "port": 443, 
          "skin": "nasLogin"
        }
      ]
    }, 
    "ssh": {
      "enabled": false, 
      "instance_defaults": {}, 
      "instances": [
        {
          "enabled": false, 
          "name": "Default SSH server", 
          "port": 22, 
          "preauth_banner": "", 
          "version": "SSH-2.0-OpenSSH_5.1p1 Debian-4"
        }
      ]
    }
  }, 
  "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,
  "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
}
 
        Copied!

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
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225

← Bundles Cloud Canaries →

# Configure Services

# Configure Bird

Required Parameters

Optional Parameters

Response

Example

# Configure Bird with Personality

Required Parameters

Optional Parameters

Response

Example

# Share Upload

# Check Share Upload Status

Required Parameters

Response

Example

# End Share Upload

Required Parameters

Optional Parameters

Response

Example

# Start Share Upload

Required Parameters

Response

Example

# Webroot Upload

# Check Webroot Upload Status

Required Parameters

Response

Example

# End Webroot Upload

Required Parameters

Response

Example

# Start Webroot Upload

Required Parameters

Response

Example

# Settings Object