Working with Rules

Stability: Stable

Rules are written in the Aperture policy language which allows you write rules in a human readable form. The access control system of the Joyent Cloud uses a subset of the Aperture policy language, and that's what we describe here.

The general form of a rule is:

CAN <actions>  [IF | WHEN | WHERE] <conditions>`

You can use any of IF, WHEN, or WHERE to make the condition easier to read.

The default permission for all resources is to deny access. The rules of a policy enable access.

This is what rules look like:

CAN getobject and getdirectory IF sourceip = 1.2.3.0/24 OR sourceip = 3.2.1.0/24
CAN putobject IF overwrite = false
CAN getobject IF fromjob = true
CAN putobject IF day IN (Monday, Tuesday, Wednesday, Thursday, Friday)

The actions for Manta and CloudAPI are listed in the tables below.

Manta Actions

For Manta, the action part of a rule operates on Manta objects.

Directory Actions

Action Manta API Endpoint Notes
putdirectory [PutDirectory] create directories, update directory metadata
getdirectory [ListDirectory] list contents of directories
deletedirectory [DeleteDirectory] delete (empty) directories

Object Actions

Action Manta API Endpoint Notes
putobject [PutObject]
[PutMetadata]
create objects, overwrite objects, update object metadata
getobject [GetObject] read object, get archived job stats
deleteobject [DeleteObject] delete objects

SnapLink Actions

Action Manta API Endpoint Notes
putlink [PutSnapLink] create snaplinks (You must also have getobject access on the source.)

Job Actions

Action Manta API Endpoint Notes
createjob [CreateJob] create jobs
listjobs [ListJobs] list jobs
getjob [GetJob]
[GetJobOutput]
[GetJobInput]
[GetJobFailures]
[GetJobErrors]
get live job status, errors, inputs, and outputs
managejob [AddJobInputs]
[EndJobInput]
[CancelJob]
add input keys to jobs, end job input, cancel jobs

CloudAPI Actions

For CloudAPI, the action part of a rule operates on CloudAPI endpoints.

Account Actions

Action CloudAPI Endpoint Command Line Interface
getaccount [GetAccount] sdc-getaccount
updateaccount [UpdateAccount] sdc-updateaccount

Key Actions

Action CloudAPI Endpoint Command Line Interface
listkeys [ListKeys] sdc-listkeys
getkey [GetKey] sdc-getkey
createkey [CreateKey] sdc-createkey
deletekey [DeleteKey] sdc-deletekey

User Actions

Action CloudAPI Endpoint Command Line Interface
listusers [ListUsers] sdc-user list
getuser [GetUser] sdc-user get
createuser [CreateUser] sdc-user create
updateuser [UpdateUser] sdc-user update
changeuserpassword [ChangeUserPassword] sdc-user change-password
deleteuser [DeleteUser] sdc-user delete

Role Actions

Action CloudAPI Endpoint Command Line Interface
listroles [ListRoles] sdc-role list
getrole [GetRole] sdc-role get
createrole [CreateRole] sdc-role create
updaterole [UpdateRole] sdc-role update
deleterole [DeleteRole] sdc-role update

Role Tag Actions

Action CloudAPI Endpoint Command Line Interface
setroletags [SetRoleTags] sdc-chmod

Policy Actions

Action CloudAPI Endpoint Command Line Interface
listpolicies [ListPolicies] sdc-policy list
getpolicy [GetPolicy] sdc-policy get
createpolicy [CreatePolicy] sdc-policy create
updatepolicy [UpdatePolicy] sdc-policy update
deletepolicy [DeletePolicy] sdc-policy delete

User SSH Key Actions

Action CloudAPI Endpoint Command Line Interface
listuserkeys [ListUserKeys] sdc-user keys
getuserkey [GetUserKey] sdc-user key
createuserkey [CreateUserKey] sdc-user upload-key
deleteuserkey [DeleteUserKey] sdc-user delete-key

Datacenter Actions

Action CloudAPI Endpoint Command Line Interface
listdatacenters [ListDataCenters] sdc-listdatacenters
getdatacenter [GetDatacenter] none

Image Actions

Action CloudAPI Endpoint Command Line Interface
listimages [ListImages] sdc-listimages
getimage [GetImage] sdc-getimage
deleteimage [DeleteImage] sdc-deleteimage
exportimage [ExportImage] sdc-exportimage
createimagefrommachine [CreateImageFromMachine] sdc-createimagefrommachine
updateimage [UpdateImage] sdc-updateimage

Package Actions

Action CloudAPI Endpoint Command Line Interface
listpackages [ListPackages] sdc-listpackages
getpackage [GetPackage] sdc-getpackage

Machine Actions

Action CloudAPI Endpoint Command Line Interface
listmachines [ListMachines] sdc-listmachines
getmachine [GetMachine] sdc-getmachine
createmachine [CreateMachine] sdc-createmachine
stopmachine [StopMachine] sdc-stopmachine
startmachine [StartMachine] sdc-startmachine
rebootmachine [RebootMachine] sdc-rebootmachine
resizemachine [ResizeMachine] sdc-resizemachine
renamemachine [RenameMachine] sdc-renamemachine
enablemachinefirewall [EnableMachineFirewall] sdc-enablemachinefirewall
disablemachinefirewall [DisableMachineFirewall] sdc-disablemachinefirewall
createmachinesnapshot [Createmachinesnapshot] sdc-createmachinesnapshot
startmachinefromsnapshot [StartMachineFromSnapshot] sdc-startmachinefromsnapshot
listmachinesnapshots [ListMachineSnapshots] sdc-listmachinesnapshots
getmachinesnapshot [GetMachineSnapshot] sdc-getmachinesnapshot
deletemachinesnapshot [DeleteMachineSnapshot] sdc-deletemachinesnapshot
updatemachinemetadata [UpdateMachineMetadata] sdc-updatemachinemetadata
getmachinemetadata [GetMachineMetadata] sdc-getmachinemetadata
deletemachinemetadata [DeleteMachineMetadata] sdc-deletemachinemetadata
deleteallmachinemetadata [DeleteAllMachineMetadata] sdc-deletemachinemetadata
addmachinetags [AddMachineTags] sdc-addmachinetags
replacemachinetags [ReplaceMachineTags] sdc-replacemachinetags
listmachinetags [ListMachineTags] sdc-listmachinetags
getmachinetag [GetMachineTag] sdc-getmachinetag
deletemachinetag [DeleteMachineTag] sdc-deletemachinetag
deletemachinetags [DeleteMachineTags] sdc-deletemachinetag
deletemachine [DeleteMachine] sdc-deletemachine
machineaudit [MachineAudit] sdc-getmachineaudit

Analytics Actions

Action CloudAPI Endpoint Command Line Interface
describeanalytics [DescribeAnalytics] sdc-describeanalytics
listinstrumentations [ListInstrumentations] sdc-listinstrumentations
getinstrumentation [GetInstrumentation] sdc-getinstrumentation
getinstrumentationvalue [GetInstrumentationValue] sdc-getinstrumentation
getinstrumentationheatmap [GetInstrumentationHeatmap] none
getinstrumentationheatmapdetails [GetInstrumentationHeatmapDetails] none
createinstrumentation [CreateInstrumentation] sdc-createinstrumentation
deleteinstrumentation [DeleteInstrumentation] sdc-deleteinstrumentation

Firewall Rule Actions

Action CloudAPI Endpoint Command Line Interface
listfirewallrules [ListFirewallRules] sdc-listfirewallrules
getfirewallrule [GetFirewallRule] sdc-getfirewallrule
createfirewallrule [CreateFirewallRule] sdc-createfirewallrule
updatefirewallrule [UpdateFirewallRule] sdc-updatefirewallrule
enablefirewallrule [EnableFirewallRule] sdc-enablefirewallrule
disablefirewallrule [DisableFirewallRule] sdc-disablefirewallrule
deletefirewallrule [DeleteFirewallRule] sdc-deletefirewallrule
listmachinefirewallrules [ListmachineFirewallRules] sdc-listmachinefirewallrules
listfirewallrulemachines [ListFirewallRuleMachines] sdc-listfirewallrulemachines

Network Actions

Action CloudAPI Endpoint Command Line Interface
listnetworks [ListNetworks] sdc-listnetworks
getnetwork [GetNetwork] sdc-getnetwork

Conditions

You can add conditions to specify when a rule is valid. For example, you may want to limit contractor access to requests from a specific IP address.

The following operators are valid in condition expressions. Operators must be delimited with spaces.

Operator Description
= equal
!= not equal
< less than
> greater than
<= less than or equal
>= greater than or equal
AND and boolean values, list separator
OR or boolean values
NOT boolean negation
IN array membership
(, ) grouping

Lists can be given in various forms:

You can use fuzzy matches and regular expressions.

ops_* matches a string beginning with ops_. Use \ to escape asterisks: Star\*Command.

Follow JavaScript regular expressions with ::regex. If you want to keep people from using curl, you might do something like this:

CAN getobject IF user-agent != /^curl/::regex

(Note that it's very simple to change the user agent in curl.)

General Conditions

Name Description Example
activeRoles List of active roles. CAN listnetworks AND getnetwork WHEN activeRoles = *ops
date Date of the request. CAN getobject IF date > "25 Dec 2014"
day Day of the week the request is made. Valid values:
monday mon m
tuesday tue t
wednesday wed w
thursday thu th
friday fri f
saturday sat s
sunday sun su
CAN createuser IF day IN (Monday, Wednesday, Friday)
sourceip Source ip address of the request. CAN listpolicies IF sourceip = 127.0.0.1
time Time of day the request was made. CAN createrole IF time > 13:00 AND time < 21:00
user-agent User agent of the request. CAN getobject IF user-agent != /^curl/::regex

Time and date can be given in any format that JavaScript Date.parse() can parse. All times and dates are UTC.

IP addresses are IPv4 or IPv6. CIDR ranges are valid.

CloudAPI Conditions

These conditions apply only to CloudAPI operations.

Name Description Example
ips List of machine IPs when if action is machine related. CAN deletemachine WHEN ips IN (10.17.12/24)
tag_tagName::string The value of a machine tag. CAN rebootmachine IF tag_rebootable::string != never

Manta Conditions

These conditions apply only to Manta requests.

Name Description Example
fromjob True if the request was made from within a Manta job. CAN putobject IF fromjob = true
overwrite True if a request is overwriting an existing object or metadata. CAN putobject IF overwrite = false