policy

Definition

The policy command has 10 subcommands:

  • generate-secret
  • list-users
  • rbac-attach
  • rbac-detach
  • rbac-get
  • rbac-status
  • validation-add
  • validation-remove
  • validation-get
  • validation-list

These commands allow the user to manage role-based access control policy and runtime validation for Fugue.

Note: Runtime validations (and validation-* commands) are only allowed on the paid version of Fugue.

Usage

fugue [global options] policy [options] [command] [command arguments]

Subcommands

generate-secret
Generate a new secret for a specific user.
list-users
Display a list of all users.
rbac-attach
Attach a policy to the Conductor.
rbac-detach
Remove the policy from the Conductor.
rbac-get
Download the policy on the Conductor to the current working directory.
rbac-status
Query the status of the RBAC policy.
validation-add
Add a new validation library to the Conductor.
validation-remove
Remove a validation library from the Conductor.
validation-get
Retrieve a validation library from the Conductor.
validation-list
List validation libraries installed on the Conductor.

Options

Global options are detailed here.

-h | --help
Show help text. The help flag is available throughout the CLI in both an application-level and command-level context. It enables a user to view help text for any command within the Fugue CLI.

Policy Subcommands

generate-secret

Definition

Generate a new user secret, or access token, for the provided <user_id>. The <user_id> must exist on a policy that has been set on the Conductor. If a user secret already exists for the provided <user_id>, this command will expire the existing secret and create a new one.

Note: The field user_id corresponds to user in the credentials file.

Usage

fugue policy generate-secret [options] <user_id>

Options

-y | --yes
Suppress confirmation dialogs.
--json
Emit output as JSON.
-h | --help
Show help text.

Arguments

<user_id>
The user to generate the secret for. Required.

list-users

Definition

Display the list of users from the policy that has been set on the Conductor.

Usage

fugue policy list-users [options]

Options

--json
Emit output as JSON.
-h | --help
Show help text.

rbac-attach

Definition

Attach the provided <policy_file> to the Conductor. A policy is a Ludwig composition that defines RBAC rules.

Note: Fugue run will accept an RBAC policy composition or even a mixture of RBAC and standard library types, but it will have no effect.

Usage

fugue policy rbac-attach [options] <policy_file>

Options

--json
Emit output as JSON.
-h | --help
Show help text.
--werror
Treats any lwc compiler warnings as an error and forces the CLI to exit.

Arguments

<policy_file>
The policy to be attached to the Conductor. Required.

rbac-detach

Definition

Detach the currently applied policy from the Conductor.

Usage

fugue policy rbac-detach [options]

Options

-y | --yes
Suppress confirmation dialogs.
--json
Emit output as JSON.
-h | --help
Show help text.

rbac-get

Definition

Download the policy that has been set on the Conductor to the current working directory, or optionally, to <destination>. The downloaded file contains the uncompiled content of the Ludwig policy in a gzipped tarball (.tar.gz).

Usage

fugue policy rbac-get [options] <destination>

Options

--stdout
Display retrieved policy via standard output.
-h | --help
Show help text.

Arguments

<destination>
The file to which the policy should be downloaded.

rbac-status

Definition

Query the status of the RBAC policy. Status is either Attached or Detached.

Usage

fugue policy rbac-status [options]

Options

--json
Emit output as JSON.
-h | --help
Show help text.

validation-add

Definition

Add a new validation library to the Conductor. Validation library names must be unique. After a validation library is added to the Conductor, only compositions that pass validation will be run.

At the time fugue policy validation-add is executed, if the Conductor is running any processes that would fail validation, the library will not be uploaded, and you’ll see an error message:

[ ERROR ] No validation library created: Failed to validate against existing compositions.

Usage

fugue policy validation-add [options] <validation_file>

Options

--json
Emit output as JSON.
--h | --help
Show help text.
--werror
Treats any lwc compiler warnings as an error and forces the CLI to exit.

Arguments

--name <name>
Name of the new validation library. Required.

validation-remove

Definition

Remove a validation library from the Conductor. When a validation library is removed from the Conductor, those validations are no longer enforced.

Usage

fugue policy validation-remove [options] <name>

Options

--json
Emit output as JSON.
-y | --yes
Suppress confirmation dialogs.
-h | --help
Show help text.

Arguments

<name>
Name of the validation library to be removed. Required.

validation-get

Definition

Retrieve a validation library (composition) from the Conductor. This downloads the library to the current working directory, or optionally, to <destination>. The downloaded file is a Ludwig snapshot, containing several other files:

MANIFEST
File containing the name of the validation library and the version of lwc.
env.json
JSON file containing environment variables and file mapping.
lib
A folder containing a copy of the Fugue Standard Library modules and any other libraries required for validations.
src
A folder containing the entry point for the validation.

Usage

fugue policy validation-get [options] <name>

Options

--json
Emit output as JSON.
--dest <destination>
Location to download the validation library to.
-h | --help
Show help text.

Arguments

<name>
Name of the validation library to be retrieved. Required.

validation-list

Definition

List validation libraries installed on the Conductor. You may optionally use <prefix> to filter the list to libraries that start with the provided argument.

Usage

fugue policy validation-list [options] <prefix>

Options

<prefix>
Show only libraries matching this prefix.
--json
Emit output as JSON.
-h | --help
Show help text.

Examples

Attaching a policy to the Conductor

Attaching an RBAC policy to the Conductor allows the Conductor to enforce that policy’s rules. The Conductor will also create Fugue users listed in the policy.

To attach a policy to the Conductor, use the policy rbac-attach command:

fugue policy rbac-attach MyPolicy.lw

The CLI will compile the policy, upload it to S3, and ask the Conductor to apply the new policy. If successful, the CLI output will look like this:

Compiling Ludwig file MyPolicy.lw ...
[ OK ] Successfully compiled. No errors.

Uploading policy to S3 ...
[ OK ] Successfully uploaded.

Requesting the Conductor set new policy ...
[ DONE ] Policy uploaded and applied.

If there is a compilation error, the CLI will return an error message, and the policy will not be attached to the Conductor.

A newly-attached policy will overwrite the current policy on the Conductor, as only one policy may be set at a time.

Detaching a policy from the Conductor

Detaching a policy from the Conductor returns the Conductor to single-user mode, where root is the active user.

To remove a policy from the Conductor, use the policy rbac-detach command:

fugue policy rbac-detach

The CLI will prompt for confirmation, then produce output like this:

[ WARN ] Are you sure you want to detach the policy from the Conductor? [y/N]: y

Detaching policy from Conductor ...
[ DONE ] Policy detached.

Note: If users were declared in the policy that was removed, they still exist and their secrets are still set; they just cannot perform any actions. To permit the users to take action again, reattach the policy file with policy rbac-attach.

Downloading the policy from the Conductor

You can download the current policy attached to the Conductor. The downloaded file contains the uncompiled content of the Ludwig policy as a gzipped tarball (.tar.gz). The .tar.gz format is made using Ludwig snapshot semantics. To retrieve the file, use the policy rbac-get command:

fugue policy rbac-get

You’ll see output like this:

[ fugue policy ] Requesting policy document from the Conductor.

[ OK ] Retrieved policy document location

[ fugue policy ] Downloading the policy document.

[ DONE ] Policy document saved to ./policy20170605201915.tar.gz

If you want to save the policy to a specific location, specify the filename as an argument:

fugue policy rbac-get ~/mypolicy.tar.gz

Listing Fugue users

Fugue users are created when they’re declared in a policy document attached to the Conductor. To see a list of all Fugue users, use policy list-users:

fugue policy list-users

You’ll see a table like this:

Fugue User list for becki/xxxxxxxxxxxx - Mon Jan 23 2017 5:35pm

User Id    Enabled    Created      Updated
---------  ---------  -----------  -----------
becki      yes        Wed 1:18pm   Wed 3:00pm
root       yes        Dec 29 2016  Dec 29 2016
alice      no         2:53pm       2:53pm

[ HELP ] To enable a user, run "fugue policy generate-secret <user_id>".
User Id
The user’s ID in Fugue’s RBAC system
Enabled
Whether credentials have been generated for a user
Created
When the user was created
Updated
When the user was last updated

Generating a secret for a user

Generating a secret, or access token, for a user enables that user to operate Fugue, assuming both the user and rules pertaining to that user have been declared in the policy attached to the Conductor. You can also generate a secret for a user who already has one; the existing secret will expire and Fugue will create a new one.

To generate a user secret, use the policy generate-secret command:

fugue policy generate-secret alice

You’ll see output like this:

[ fugue policy ] Requesting the Conductor generate a secret for: alice ...

User Credential Details:

   User ID: alice
   User Secret: 7y4sK8ZwbpEXAMPLEEXAMPLEEAMPLEEXAMPLEEXAMPLE

[ DONE ] Secret successfully generated.

Root credentials are generated upon install, or upon upgrade if upgrading from a version of Fugue without the RBAC feature.

Warning

Do not lose your root credentials. They cannot be replaced with the policy generate-secret command. If you have lost your root credentials, see the reset-secret command or contact support@fugue.co.

Checking RBAC status

To determine whether an RBAC policy has been attached to the Conductor, execute the policy rbac-status command:

fugue policy rbac-status

If an RBAC policy has been attached, the output will say “Attached”:

[ fugue policy rbac-status ] Querying Conductor...

Status: Attached

If no RBAC policy is currently attached, the output will say “Detached”:

[ fugue policy rbac-status ] Querying Conductor...

Status: Detached

Adding a validation library to the Conductor

When you add a validation library to the Conductor, all future processes are tested against the validations. If a composition fails validation, it will not be run.

Validation library names must be unique. To add a validation library to the Conductor, use the policy validation-add command and give your new validation library a name with the required option --name:

fugue policy validation-add --name usWest2Only UsWest2OnlyValidation.lw

The Fugue CLI will compile the validation library, upload it to S3, and ask the Conductor to create the new validation library. You’ll see output like this:

[fugue validation] Compiling Ludwig File UsWest2OnlyValidation.lw
[ OK ] Successfully compiled. No errors.

Uploading validation library to S3 ...
[ OK ] Successfully uploaded.

Requesting the Conductor create new validation library ...
[ DONE ] Validation library 'usWest2Only' uploaded and added to the Conductor.

Removing a validation library from the Conductor

Removing a validation library from the Conductor means that those validations are no longer enforced.

To remove a validation library from the Conductor, use the policy validation-remove command with the name of the library. This should be the name you entered during policy validation-add, not the filename of the composition:

fugue policy validation-remove usWest2Only

The CLI will prompt for confirmation and, upon y, return output like the following:

[fugue validation] Deleting Validation Library: 'usWest2Only'

[ WARN ] Are you sure you want to delete this validation library: 'usWest2Only'? [y/N]: y

Requesting the Conductor to delete validation library: 'usWest2Only' ...
[ DONE ] The Conductor is deleting the validation library: 'usWest2Only'

Retrieving a validation library from the Conductor

You can download a validation library from the Conductor. The validation library is downloaded as a gzipped tarball (.tar.gz). The .tar.gz format is made using Ludwig snapshot semantics. To retrieve the file, use the policy validation-get command with the name of the library. This should be the name you entered during policy validation-create, not the filename of the composition:

fugue policy validation-get usWest2Only

You’ll see the following output:

[fugue validation] Downloading Validation Library usWest2Only

Retrieving validation metatdata from the Conductor...

Downloading the validation library to /Users/main-user/projects/usWest2Only.tar.gz
Successfully downloaded usWest2Only to /Users/main-user/projects/usWest2Only.tar.gz

By default, Fugue saves the file to your current working directory. If you want to save the policy to a specific location, specify the target directory as an argument with the --dest option:

fugue policy validation-get usWest2Only --dest ~/

Listing validation libraries on the Conductor

To see a list of all validation libraries currently enabled, use the policy validation-list command:

fugue policy validation-list

You’ll see a table:

Fugue Validation Libraies for user/xxxxxxxxxxxx - Wed Jun 28 2017 4:36pm

Name         Created     File Name                 Sha256
-----------  ----------  ------------------------  --------
usWest2Only  Mon 4:00pm  UsWest2OnlyValidation.lw  7f7ab649
Name
The name of the validation library
Created
When the validation library was created
Filename
The original filename of the validation library
Sha256
The first 8 digits of the SHA-256 hash for the validation library

To view the full SHA for a validation library, use the --json option:

fugue policy validation-list --json
[
    {
        "created": 1498507220,
        "file_name": "UsWest2OnlyValidation.lw",
        "name": "usWest2Only",
        "sha256": "7f7ab649212af16f794d4a8a2e4aef3ee3b0933ecb454c6c3a0bfba86425e00f"
    }
]