diff --git a/website/content/docs/api-clients/api.mdx b/website/content/docs/api-clients/api.mdx index a851f19d0..1164e3ad0 100644 --- a/website/content/docs/api-clients/api.mdx +++ b/website/content/docs/api-clients/api.mdx @@ -10,7 +10,7 @@ description: |- Boundary's API is a a JSON-based HTTP API that adheres to a set of standards that are rigidly followed. At its core, it is a standards-compliant JSON API for both input and output. -Before reading this page, it is useful to understand Boundary's [domain model](/docs/concetps/domain-model) to be aware of the terminology used here. +Before reading this page, it is useful to understand Boundary's [domain model](/docs/concepts/domain-model) to be aware of the terminology used here. Boundary's API is also described via OpenAPI v2; the version corresponding to any tag of Boundary's source code can be found in Boundary's [GitHub repository](https://github.com/hashicorp/boundary/blob/main/internal/gen/controller.swagger.json). @@ -18,13 +18,13 @@ Boundary's current API version is 1; all API paths begin with `/v1/`. ## Status Codes -* `2XX`: Boundary returns a code between `200` and `299` on success. Generally this is `200`, but implementations should be prepared to accept any `2XX` status code as indicating success. If a call returns a `2XX` code that is not `200`, it will follow well-understood semantics for those status codes. -* `400`: Boundary returns `400` when a command cannot be completed due to invalid user input, except for a properly-formatted identifier that does not map to an existing resource, which will return a `404` as discussed below. -* `401`: Boundary returns `401` if no authentication token is provided or if the provided token is invalid. A valid token that simply does not have permission for a resource will return a `403` instead. A token that is invalid or missing, but where the anonymous user (`u_anon`) is able to successfully perform the action, will not return a `401` but instead will return the result of the action. -* `403`: Boundary returns `403` if a provided token was valid but does not have the grants required to perform the requested action. -* `404`: Boundary returns `404` if a resource cannot be found. Note that this happens _prior_ to authentication/authorization checking in nearly all cases as the resource information (such as its scope, available actions, etc.) is a required part of that check. As a result, an action against a resource that does not exist will return a `404` instead of a `401` or `403`. While this could be considered an information leak, since IDs are randomly generated and this only discloses whether an ID is valid, it's tolerable as it allows for far simpler and more robust client implementation. -* `405`: Boundary returns a `405` to indicate that the method (HTTP verb or custom action) is not implemented for the given resource. -* `500`: Boundary returns `500` if an error occurred that is not (directly) tied to invalid user input. If a `500` is generated, information about the error will be logged to Boundary's server log but is not generally provided to the client. +- `2XX`: Boundary returns a code between `200` and `299` on success. Generally this is `200`, but implementations should be prepared to accept any `2XX` status code as indicating success. If a call returns a `2XX` code that is not `200`, it will follow well-understood semantics for those status codes. +- `400`: Boundary returns `400` when a command cannot be completed due to invalid user input, except for a properly-formatted identifier that does not map to an existing resource, which will return a `404` as discussed below. +- `401`: Boundary returns `401` if no authentication token is provided or if the provided token is invalid. A valid token that simply does not have permission for a resource will return a `403` instead. A token that is invalid or missing, but where the anonymous user (`u_anon`) is able to successfully perform the action, will not return a `401` but instead will return the result of the action. +- `403`: Boundary returns `403` if a provided token was valid but does not have the grants required to perform the requested action. +- `404`: Boundary returns `404` if a resource cannot be found. Note that this happens _prior_ to authentication/authorization checking in nearly all cases as the resource information (such as its scope, available actions, etc.) is a required part of that check. As a result, an action against a resource that does not exist will return a `404` instead of a `401` or `403`. While this could be considered an information leak, since IDs are randomly generated and this only discloses whether an ID is valid, it's tolerable as it allows for far simpler and more robust client implementation. +- `405`: Boundary returns a `405` to indicate that the method (HTTP verb or custom action) is not implemented for the given resource. +- `500`: Boundary returns `500` if an error occurred that is not (directly) tied to invalid user input. If a `500` is generated, information about the error will be logged to Boundary's server log but is not generally provided to the client. ## Path Layout @@ -34,22 +34,22 @@ Boundary follows a predictable path layout. There are two fundamental types of U Collections of resources are top level paths with plural English names for the resource, e.g. `/roles` and `/hosts`. Collections support the following operations: -* Creation of new resources within that collection -* Listing of resources within that collection +- Creation of new resources within that collection +- Listing of resources within that collection All collection operations require supplying the enclosing resource. Depending on the collection type, this will be one of the following: -* A scope, indicating the scope in which an operation should take place. For instance, a POST to `/roles` would need to indicate whether the role should be created within the `global` scope or an org-level scope like `o_1234567890`. -* A parent resource of the appropriate type. For instance, hosts and host sets are child resources of host catalogs. When creating a new host set within a host catalog, a POST to `/host-sets` would need to indicate the host catalog ID with which the host-set should be associated. +- A scope, indicating the scope in which an operation should take place. For instance, a POST to `/roles` would need to indicate whether the role should be created within the `global` scope or an org-level scope like `o_1234567890`. +- A parent resource of the appropriate type. For instance, hosts and host sets are child resources of host catalogs. When creating a new host set within a host catalog, a POST to `/host-sets` would need to indicate the host catalog ID with which the host-set should be associated. ### Resources Resources themselves are defined by ID specifiers within a collection path, e.g. `/roles/r_1234567890`. Resources support the following operations: -* Reading a resource's properties -* Updating a resource's properties -* Deleting a resource -* Custom methods specific to a resource type +- Reading a resource's properties +- Updating a resource's properties +- Deleting a resource +- Custom methods specific to a resource type Depending on the resource type, various parameters may be available. Some are common across all resource types (e.g. `name` and `description`); others are available only for specific types. Further, some concrete-types of abstract resources include an opaque `attributes` JSON object with type-specific values. @@ -71,9 +71,9 @@ The following method conventions are used within Boundary's API: `PATCH` is used to update a resource's parameters. The following are behaviors to be aware of when using `PATCH`: -* In nearly all cases, a `version` parameter is required. This is used for check-and-set, to ensure that the update operation is being performed against a known resource. The version parameter is returned from a `GET` operation on the resource so the current version, along with the resource's other current values, can be looked up at any time. -* Passing a JSON `null` for a parameter has the effect of reverting that parameter to its default. For some parameters (e.g. `name`) this will simply clear the value (as the default `name` for a resource is empty); for other parameters this will revert to the current defaults within Boundary. -* All parameters specified as part of a `PATCH` operation will be considered to be parameters that should be updated. +- In nearly all cases, a `version` parameter is required. This is used for check-and-set, to ensure that the update operation is being performed against a known resource. The version parameter is returned from a `GET` operation on the resource so the current version, along with the resource's other current values, can be looked up at any time. +- Passing a JSON `null` for a parameter has the effect of reverting that parameter to its default. For some parameters (e.g. `name`) this will simply clear the value (as the default `name` for a resource is empty); for other parameters this will revert to the current defaults within Boundary. +- All parameters specified as part of a `PATCH` operation will be considered to be parameters that should be updated. ### DELETE diff --git a/website/content/docs/concepts/index.mdx b/website/content/docs/concepts/index.mdx index 3fef9b438..7f7fb0065 100644 --- a/website/content/docs/concepts/index.mdx +++ b/website/content/docs/concepts/index.mdx @@ -6,23 +6,27 @@ description: |- An introduction to Boundary concepts and architecture. --- - # Concepts + Boundary is a tool for managing identity-based access for modern, dynamic infrastructure. Just as infrastructure itself can be complex, at first glance Boundary can seem complex as well. As a result, it's helpful to understand how Boundary organizes security principals and resources, as well as how it allows you define granular permissions to those principals. A glossary of terms is contained in the [domain model](/docs/concepts/domain-model) section. # Identity & Permission Management + Identity is a core concept in Boundary. Identity is represented by two types of resources, mapping to common security principals: -* [Users](/docs/concepts/domain-model/users), which represent distinct entities that can be tied to authentication accounts -* [Groups](/docs/concepts/domain-model/groups), which are collections of Users that allow for easier access management +- [Users](/docs/concepts/domain-model/users), which represent distinct entities that can be tied to authentication accounts +- [Groups](/docs/concepts/domain-model/groups), which are collections of Users that allow for easier access management -[Roles](/docs/concepts/domain-model/roles) map users and groups to a set of [grants](/docs/concepts/domain-model/grants), which provide the ability to perform actions within the system. +[Roles](/docs/concepts/domain-model/roles) map users and groups to a set of [grants](/docs/concepts/security/permissions), which provide the ability to perform actions within the system. # Resource Management + Boundary enables flexible management of the hosts and services for which it can broker access. Boundary administrators define [host catalogs](/docs/concepts/domain-model/host-catalogs) that contain information about [hosts](/docs/concepts/domain-model/hosts). These hosts are then collected into [host sets](/docs/concepts/domain-model/host-sets) which represent sets of equivalent hosts. Finally, [targets](/docs/concepts/domain-model/targets) tie together host sets with connection information. Final access to a resource is granted via [roles](/docs/concepts/domain-model/roles) that provide authorization to create sessions against these targets. -# Next Steps +# Next Steps + Be sure Boundary is able to run locally with the instructions at [Getting Started](/docs/getting-started). Then, learn how to create targets and initiate a session with [Connect to Your First Target](/docs/getting-started/connect-to-target). # Further Reading -For more information see our general recommendations for [deployment architecture](/docs/installing/production), and see the [security model](/docs/concepts/security-model) documentation for an explanation of the security foundations of Boundary. + +For more information see our general recommendations for [deployment architecture](/docs/installing/high-availability), and see the [security model](/docs/concepts/security) documentation for an explanation of the security foundations of Boundary. diff --git a/website/content/docs/getting-started/index.mdx b/website/content/docs/getting-started/index.mdx index 01d7e1bf3..633b1da9f 100644 --- a/website/content/docs/getting-started/index.mdx +++ b/website/content/docs/getting-started/index.mdx @@ -13,15 +13,15 @@ Before getting started with Boundary, it's important to understand a few key con The examples in Getting Started all revolve around running in `dev mode`. There are a few requirements for running dev mode: -1. Docker is installed +1. [Docker](https://docs.docker.com/get-docker/) is installed 2. A route to download the [Postgres Docker image](https://hub.docker.com/_/postgres) is available or a local image cache is available -3. A boundary binary in your $PATH +3. A [Boundary binary](https://www.boundaryproject.io/downloads) in your \$PATH ## What is Dev Mode? Dev mode is an all-in-one installation method for getting started with Boundary quickly. As the name implies, dev mode is not a production installation method, but instead a way to get Boundary running with a Postgres -database easily. Do not use dev mode in a production environment, see [Production Installation](/docs/installing/production) section for +database easily. Do not use dev mode in a production environment, see [Production Installation](/docs/installing/high-availability) section for production ready deployment methods. Dev mode brings up a fully functioning instance of Boundary, including: diff --git a/website/content/docs/installing/systemd.mdx b/website/content/docs/installing/systemd.mdx index 1b4fd8a13..3bce821fc 100644 --- a/website/content/docs/installing/systemd.mdx +++ b/website/content/docs/installing/systemd.mdx @@ -1,6 +1,6 @@ --- layout: docs -page_title: Systemd Installation +page_title: Systemd Installation sidebar_title: Systemd Install description: |- How to install Boundary under Systemd on Linux @@ -8,9 +8,9 @@ description: |- # Installing Boundary under Systemd -This section covers how to install Boundary under the [Systemd]() init system on modern Linux distributions. In this section we'll cover an example of breaking out the controller and worker servers onto separate instances, though you can opt to run both on a single server. +This section covers how to install Boundary under the [Systemd](https://systemd.io/) init system on modern Linux distributions. In this section we'll cover an example of breaking out the controller and worker servers onto separate instances, though you can opt to run both on a single server. -## Filesystem Configuration +## Filesystem Configuration `TYPE` below can be either `worker` or `controller` if you want to run them independently, e.g. for high availability. If you want to run combined nodes, modify as desired. @@ -24,7 +24,7 @@ This section covers how to install Boundary under the [Systemd]() init system on ## User & Group Configuration -We recommend running Boundary as a non-root user, and use this user to manage the Boundary process running under systemd. The example init files here do exactly this, and our example install script below creates a user and group on Debian-like Ubuntu systems as an example. +We recommend running Boundary as a non-root user, and use this user to manage the Boundary process running under systemd. The example init files here do exactly this, and our example install script below creates a user and group on Debian-like Ubuntu systems as an example. ## Systemd Unit file diff --git a/website/content/docs/releases/release-notes/v0_1_0.mdx b/website/content/docs/releases/release-notes/v0_1_0.mdx index ad3ecc6f4..cbc1ad882 100644 --- a/website/content/docs/releases/release-notes/v0_1_0.mdx +++ b/website/content/docs/releases/release-notes/v0_1_0.mdx @@ -15,10 +15,10 @@ v0.1.0 is the first release of Boundary. As a result there are no changes, impro In this initial release, Boundary provides: - Password-based authentication -- Authenticated and authorized [TCP-based sessions](docs/common-workflows/manage-sessions). +- Authenticated and authorized [TCP-based sessions](/docs/common-workflows/manage-sessions). - Identity and access management providing [role-based controls](/docs/common-workflows/manage-roles) for principals. - A user interface for administration of Boundary resources. -- A [Terraform provider](https://github.com:hashicorp/terraform-provider-boundary) for managing Boundary resources. +- A [Terraform provider](https://github.com/hashicorp/terraform-provider-boundary) for managing Boundary resources. - A fully instrumented command line interface for managing Boundary and for establishing and managing sessions. -- A fully instrumented [Boundary golang SDK](/docs/developing/sdk). +- A fully instrumented [Boundary golang SDK](/docs/api-clients/go-sdk). - A log of Boundary sessions exposed through Boundary's administrator UI and postgres database.