`bm alias set`

Syntax

The bm alias set command adds or updates an alias to the local bm configuration.

EXAMPLE

The following command adds an alias for a Buckit deployment mybuckit running at the URL https://mybuckit.example.net. bm uses the specified username and password for authenticating to the Buckit deployment:

bm alias set mybuckit https://mybuckit.example.net buckitadminuser buckitadminpassword

If the mybuckit alias already exists, the command overwrites that alias with the new URL, access key, and secret key.

SYNTAX

The bm alias set command has the following syntax:

bm [GLOBALFLAGS] alias set \
                 [--api "string"]                           \
                 [--path "string"]                          \
                 ALIAS                                      \
                 URL                                        \
                 ACCESSKEY                                  \
                 SECRETKEY

Brackets [] indicate optional parameters.
Parameters sharing a line are mutually dependent.
Parameters separated using the pipe | operator are mutually exclusive.

Copy the example to a text editor and modify as-needed before running the command in the terminal/shell.

Parameters

ALIAS

Required The name to associate to the S3-compatible service. Aliases are case-sensitive and must meet the following requirements:

Contain only ASCII lower case letters (a-z), upper case letters (A-Z), numbers ([0-9]), hyphen (-), or underscore (_).
2 or more characters in length.
The first character must be a letter.

Changed in version RELEASE.2024-01-11T05-49-32Z: An alias may also be a single letter (a-z or A-Z).

Examples of some valid alias values include:

mybuckit
Test-1
A
a

URL

Required The URL to the S3-compatible service endpoint. For example:

https://buckit.example.net

ACCESSKEY

Required

The access key for authenticating to the S3 service.

SECRETKEY

Required

The secret key for authenticating to the S3 service.

--api

Optional

Specifies the signature calculation method to use when connecting to the S3-compatible service. Supports the following values:

S3v4 (Default)
S3v2

Note

AWS Signature V2 is considered deprecated by AWS. bm alias set includes this option only for S3 buckets or services still reliant on the Signature V2.

Use S3v4 unless explicitly required by the S3-compatible service. Buckit server does not rely on nor require S3v2, nor are all API operations available on S3v2.

--path

Optional

Specifies the bucket path lookup setting used by the server. Supports the following values:

"auto" (Default)
"on"
"off"

Global Flags

This command supports any of the global flags.

Examples

Add or Update an Alias for a Buckit Deployment

Use bm alias set to add an S3-compatible service for use with bm:

Example

The following command creates a new alias mybuckit pointing at a Buckit deployment at https://buckit.example.net. The alias uses the buckituser and buckitpassword credentials for performing operations against the deployment.

bm alias set mybuckit https://buckit.example.net buckituser buckitpassword

If the mybuckit alias already exists, the bm alias set command overwrites that alias with the specified arguments.

Syntax

bm alias set ALIAS HOSTNAME ACCESSKEY SECRETKEY

Replace ALIAS with the the name to associate to the Buckit service.
Replace HOSTNAME with the URL for any node in the Buckit deployment. You can alternatively specify the URL for a load balancer or reverse proxy managing connections to the Buckit deployment.
Replace ACCESSKEY and SECRETKEY with credentials for a user on the Buckit deployment.

Behavior

S3 Compatibility

The bm commandline tool is built for compatibility with the AWS S3 API and is tested with Buckit and AWS S3 for expected functionality and behavior.

Buckit provides no guarantees for other S3-compatible services, as their S3 API implementation is unknown and therefore unsupported. While bm commands may work as documented, any such usage is at your own risk.

Required Credentials and Access Control

bm alias set requires specifying an access key and corresponding secret key for the S3-compatible host. bm functionality is limited based on the policies associated to the specified credentials. For example, if the specified credentials do not have read/write access to a specific bucket, bm cannot perform read or write operations on that bucket.

For more information on Buckit Access Control, see Access Management.

For more complete documentation on S3 Access Control, see Amazon S3 Security.

For all other S3-compatible services, defer to the documentation for that service.

Certificates

The Buckit Manager CLI fetches the peer certificate, computes the public key fingerprint, and asks the user whether to accept the deployment’s certificate.

If trusted, the Buckit Manager CLI automatically adds the certificate authority to:

~/.config/bm/certs/CAs/ on Linux and other Unix-like systems.
%APPDATA%\bm\certs\CAs\ on Windows systems.