Set environment osquery target

PUT

/api/v1/environments/osquery/{env}

curl --request PUT \
  --url https://example.com/api/v1/environments/osquery/example \
  --header 'Authorization: <Authorization>' \
  --header 'Content-Type: application/json' \
  --data '{ "expires_at": "example", "version": "example" }'

Rolls the environment out to a version of the library in stages of 1%, 10%, 50% and 100% of its hosts, two hours apart; the first stage opens now. Any active rollout is replaced. Hosts at or above the version are left alone; osctrld upgrades the others when osqueryd is running. Setting the same version again starts a new rollout and retries hosts that rejected it. The rollout pauses on a rollback and needs Resume. Unknown body fields are refused, and so is expires_at: environment targets do not expire (use a node pin for a temporary override). Environment admins.

Authorizations

• ApiKeyAuth

Parameters

Path Parameters

env

required

string

Environment name or UUID

Request Body^required

Target version

Media typeapplication/json

object

expires_at

string

version

string

Example^generated

{
  "expires_at": "example",
  "version": "example"
}

Responses

200

OK

Media typeapplication/json

object

available

Available lists the library version names (no digests), ascending.

Array<string>

counts

Array<object>

object

count

integer

version

string

rollout

Rollout is the environment’s latest rollout, null when it never had one.

object

counts

object

eligible

integer

rolled_back

integer

upgraded

integer

waiting

integer

next_stage_at

string

paused

object

at

string

host

string

reason

string

request_id

string

rolled_back_hosts

RolledBackHosts is newest first, at most 50.

Array<object>

object

at

string

host

string

reason

string

stage

integer

stage_opened_at

string

stages

Array<integer>

state

string

version

string

target

object

request_id

string

updated_at

string

updated_by

string

version

string

windows_hosts

WindowsHosts is the number of Windows hosts in the environment; Windows upgrades cannot be rolled back automatically.

integer

Example^generated

{
  "available": [
    "example"
  ],
  "counts": [
    {
      "count": 1,
      "version": "example"
    }
  ],
  "rollout": {
    "counts": {
      "eligible": 1,
      "rolled_back": 1,
      "upgraded": 1,
      "waiting": 1
    },
    "next_stage_at": "example",
    "paused": {
      "at": "example",
      "host": "example",
      "reason": "example"
    },
    "request_id": "example",
    "rolled_back_hosts": [
      {
        "at": "example",
        "host": "example",
        "reason": "example"
      }
    ],
    "stage": 1,
    "stage_opened_at": "example",
    "stages": [
      1
    ],
    "state": "example",
    "version": "example"
  },
  "target": {
    "request_id": "example",
    "updated_at": "example",
    "updated_by": "example",
    "version": "example"
  },
  "windows_hosts": 1
}

400

Bad request or version not in the library

Media typeapplication/json

object

code

string

error

string

Example^generated

{
  "code": "example",
  "error": "example"
}

401

Unauthorized

Media typeapplication/json

object

code

string

error

string

Example^generated

{
  "code": "example",
  "error": "example"
}

403

Forbidden

Media typeapplication/json

object

code

string

error

string

Example^generated

{
  "code": "example",
  "error": "example"
}

404

Not found

Media typeapplication/json

object

code

string

error

string

Example^generated

{
  "code": "example",
  "error": "example"
}

413

Request body too large

Media typeapplication/json

object

code

string

error

string

Example^generated

{
  "code": "example",
  "error": "example"
}

500

Internal server error

Media typeapplication/json

object

code

string

error

string

Example^generated

{
  "code": "example",
  "error": "example"
}