diff --git a/website/content/docs/troubleshoot/common-errors.mdx b/website/content/docs/troubleshoot/common-errors.mdx new file mode 100644 index 000000000..5098d0af4 --- /dev/null +++ b/website/content/docs/troubleshoot/common-errors.mdx @@ -0,0 +1,79 @@ +--- +layout: docs +page_title: Common Error Messages +description: |- + Common error messages for Boundary +--- + +# Common Error Messages +When installing and running Boundary, there are some common messages you might see. Usually they indicate an issue in your network or in your IAM +configuration. Some of the more common errors and their solutions are listed below. If you think you have found a bug, please report the issue on +[github](https://github.com/hashicorp/boundary/issues/new/choose). + +#### Cannot connect to target: error from controller when performing authorize-session action against given target + +``` +$ boundary targets authorize-session +Error from controller when performing authorize-session action against given target + +Error information: + Kind: PermissionDenied + Message: Forbidden. + Status: 403 + context: Error from controller when performing authorize-session action against given target +``` + +This error message indicates the user does not have permission to access the requested target. Ensure the right IAM policies are configured for the +user attempting to create a session. Users need to belong to a role in the target's scope with an authorize-session grant to access the target. +[Resource table](https://www.boundaryproject.io/docs/concepts/security/permissions/resource-table) page is a great reference for how to configure +the right permission grants for Boundary roles. + +#### Error from controller when performing authorize-session action against given target + +``` +$ boundary connect -target-id $TARGET_ID +Error from controller when performing authorize-session action against given target + +Error information: + Kind: FailedPrecondition + Message: No workers are available to handle this session, or all have been filtered. + Status: 400 + context: Error from controller when performing authorize-session action against given target +``` + +This error message indicates the worker is unable to proxy connections to the target. This could be caused by a number of issues. + +**Network misconfiguration:** ensure that worker, target, and clients have the required network configurations +- Targets + - Need to allow inbound connections from workers +- Workers + - Need to allow outbound connections to a Boundary trusted control point (either the Boundary control plane or another trusted worker) + - Need to allow outbound connections to targets + - Need to allow inbound connections from clients +- Client devices + - Need to allow outbound (client->worker) connections to workers + - The target is accessible by the Worker. The same error message is thrown if the target IP is either misconfigured or inaccessible by the worker + +**Worker tag and filter misconfiguration:** If your target is using a worker filter +- Ensure the worker filter selects the intended worker(s) to proxy connections to the target. +- Ensure your intended worker(s) have the intended tags to match your target's filter + +#### Error from controller when performing authorize-session action against given target: unsupported credential *vault.baseCred + +``` +$ boundary connect ssh -target-id tssh_dmcFiVIakM +Error from controller when performing authorize-session action against given target + +Error information: + Kind: Internal + Message: targets.(Service).AuthorizeSession: targets.dynamicToWorkerCredential: unsupported credential *vault.baseCred: + parameter violation: error #100 + Status: 500 + context: Error from controller when performing authorize-session action against given target +``` +You may experience this error when attempting credential injection via Vault. Currently username_password and ssh_private_key credential +types are supported for credential injection, but only username_password can be set up using the Web UI. If you experience this error, +attempt to create the Vault ssh_private_key credential library using the CLI instead of the UI. + + + diff --git a/website/content/docs/troubleshoot/faq.mdx b/website/content/docs/troubleshoot/faq.mdx new file mode 100644 index 000000000..c3bb63586 --- /dev/null +++ b/website/content/docs/troubleshoot/faq.mdx @@ -0,0 +1,56 @@ +--- +layout: docs +page_title: FAQ +description: |- + FAQ for Boundary +--- + +# Frequently Asked Questions +#### Q: What are the networking requirements for Boundary? Do my workers need to be exposed to the public internet? +Boundary workers require inbound access from clients. This does not necessarily require that workers be exposed to the public internet. +If the client is coming from a private network (eg a corporate network), the worker needs to allow connectivity from the private network. +If the client is coming from the public internet, the worker needs to allow connectivity from the public internet. For more information, +check out the [worker networking requirements](https://cloud.hashicorp.com/docs/boundary/self-managed-workers). + +#### Q: Does Boundary require Vault? What is the integration story? +While Vault isn't a *required* secrets backend for Boundary sessions, the potential for Boundary | Vault integration is a core part of Boundary's overall +value proposition for identity-based access.There are three primary points of integration with Vault: +1. Vault can be used as a secrets backend for Boundary, offering single signon to end target systems via credential brokering. This was covered in Boundary's +[0.4 announcement](https://www.hashicorp.com/blog/announcing-hashicorp-boundary-0-4) and there are ample +[tutorials](https://learn.hashicorp.com/tutorials/boundary/vault-cred-brokering-quickstart) of this scenario. +2. Boundary can use Vault as an OIDC provider to enable sign-in with Vault's supported auth methods (even non-OIDC auth methods like Active Directory kerberos/LDAP). +This scenario is walked through in this [tutorial](https://learn.hashicorp.com/tutorials/vault/oidc-identity-provider). +3. OSS Boundary can use Vault as the external KMS that serves as Boundary's root of trust. More information on this use case can be found +[here](https://www.boundaryproject.io/docs/configuration/kms/transit). + +#### Q: What Identity Providers does Boundary Support? +Boundary supports [OIDC authentication](https://learn.hashicorp.com/tutorials/boundary/oidc-auth), which allows support for many popular IdPs +like Okta, Azure AD, Auth0, etc. For non-OIDC authentication protocols (such as LDAP), users can also log in with an OIDC bridge identity provider +such as [Vault's OIDC bridge](https://www.vaultproject.io/docs/concepts/oidc-provider) capabilities released in 1.9, [Dex](https://dexidp.io), or various others. + +#### Q: Does Boundary support Multi-factor Authentication (MFA) +Boundary Open-ID Connect (OIDC)-based authentication supports MFA if the IdP being used enforces MFA. This allows users to authenticate with an identity +provider supporting MFA, such as Azure AD, Okta, Auth0, etc. +Boundary also supports syncing permission claims between an IDP-managed identity and Boundary. This can be very useful when you want to sync group memberships +from an IDP to Boundary to assign role assignments dynamically. See Boundary's [managed groups capabilities](https://learn.hashicorp.com/tutorials/boundary/oidc-idp-groups?in=boundary/configuration). + +#### Q: Does Boundary automate the discovery and configuration of new targets (e.g. servers)? What happens if a host IP address changes? +Yes, this is one of the core competencies of Boundary. Boundary can discover new targets in two primary ways +1. Boundary's [Terraform provider](https://registry.terraform.io/providers/hashicorp/boundary/latest/docs) supports discovery of targets provisioned by Terraform +2. Boundary's [dynamic host catalog](https://learn.hashicorp.com/tutorials/boundary/aws-host-catalogs?in=boundary/oss-access-management) +agentlessly queries infrastructure providers to automate the onboarding and configuration of hosts + +All of these methods will automate the discovery and configuration of targets when their ip addresses change. Of course, static hosts can still be manually added via Boundary admin UI and CLI. + +For more information on dynamic host catalogs, please see: +- [Dynamic Host Catalog on AWS](https://learn.hashicorp.com/tutorials/boundary/aws-host-catalogs?in=boundary/access-management) +- [Dynamic Host Catalogs on Azure](https://learn.hashicorp.com/tutorials/boundary/azure-host-catalogs?in=boundary/access-management) + +#### Q: Session management capabilities - Does Boundary support live session monitoring and termination? +**Session Logging/Monitoring:** Supported. Boundary creates a session log of all sessions created between identities and targets that have been onboarded to +Boundary. You can learn how to monitor these sessions in this [tutorial](https://learn.hashicorp.com/tutorials/boundary/getting-started-connect?in=boundary/getting-started#manage-sessions). +Boundary supports audit logs for [Boundary OSS](https://learn.hashicorp.com/tutorials/boundary/event-logging) and [audit log streaming](https://cloud.hashicorp.com/docs/boundary/audit-logging) +for HCP Boundary. Audit logs for both distributions can be exported to SIEM or BI tools. + +**Session Termination:** Supported. Session termination for Boundary administrators is a supported capability, as demonstrated in this +[tutorial](https://learn.hashicorp.com/tutorials/boundary/getting-started-connect?in=boundary/getting-started#manage-sessions). diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index bf3368c44..cd7d650cc 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -311,6 +311,19 @@ } ] }, + { + "title": "Troubleshoot", + "routes": [ + { + "title": "Common Error Messages", + "path": "troubleshoot/common-errors" + }, + { + "title": "FAQ", + "path": "troubleshoot/faq" + } + ] + }, { "title": "Common Workflows", "href": "https://learn.hashicorp.com/boundary"