2021-01-03 14:25:43 +05:30
---
2021-10-27 15:23:28 +05:30
stage: Ecosystem
group: Integrations
2021-02-22 17:27:13 +05:30
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2021-01-03 14:25:43 +05:30
---
2021-12-11 22:18:48 +05:30
# Web terminals (DEPRECATED) **(FREE)**
> [Deprecated](https://gitlab.com/groups/gitlab-org/configure/-/epics/8) in GitLab 14.5.
WARNING:
This feature was [deprecated ](https://gitlab.com/groups/gitlab-org/configure/-/epics/8 ) in GitLab 14.5.
2017-08-17 22:00:37 +05:30
2022-05-07 20:08:51 +05:30
- Read more about the non-deprecated [Web Terminals accessible through the Web IDE ](../../user/project/web_ide/index.md ).
- Read more about the non-deprecated [Web Terminals accessible from a running CI job ](../../ci/interactive_web_terminal/index.md ).
---
2021-11-18 22:05:49 +05:30
With the introduction of the [Kubernetes integration ](../../user/infrastructure/clusters/index.md ),
2021-03-11 19:13:27 +05:30
GitLab can store and use credentials for a Kubernetes cluster.
GitLab uses these credentials to provide access to
2021-12-11 22:18:48 +05:30
[web terminals ](../../ci/environments/index.md#web-terminals-deprecated ) for environments.
2017-08-17 22:00:37 +05:30
2021-03-11 19:13:27 +05:30
NOTE:
2022-01-26 12:08:38 +05:30
Only users with at least the [Maintainer role ](../../user/permissions.md ) for the project access web terminals.
2021-03-11 19:13:27 +05:30
2017-08-17 22:00:37 +05:30
## How it works
A detailed overview of the architecture of web terminals and how they work
2019-07-31 22:56:46 +05:30
can be found in [this document ](https://gitlab.com/gitlab-org/gitlab-workhorse/blob/master/doc/channel.md ).
2017-08-17 22:00:37 +05:30
In brief:
2019-03-02 22:35:43 +05:30
- GitLab relies on the user to provide their own Kubernetes credentials, and to
2017-08-17 22:00:37 +05:30
appropriately label the pods they create when deploying.
2019-03-02 22:35:43 +05:30
- When a user navigates to the terminal page for an environment, they are served
2017-08-17 22:00:37 +05:30
a JavaScript application that opens a WebSocket connection back to GitLab.
2019-03-02 22:35:43 +05:30
- The WebSocket is handled in [Workhorse ](https://gitlab.com/gitlab-org/gitlab-workhorse ),
2021-02-22 17:27:13 +05:30
rather than the Rails application server.
2019-03-02 22:35:43 +05:30
- Workhorse queries Rails for connection details and user permissions. Rails
queries Kubernetes for them in the background using [Sidekiq ](../troubleshooting/sidekiq.md ).
- Workhorse acts as a proxy server between the user's browser and the Kubernetes
2017-08-17 22:00:37 +05:30
API, passing WebSocket frames between the two.
2019-03-02 22:35:43 +05:30
- Workhorse regularly polls Rails, terminating the WebSocket connection if the
2017-08-17 22:00:37 +05:30
user no longer has permission to access the terminal, or if the connection
details have changed.
2019-03-02 22:35:43 +05:30
## Security
GitLab and [GitLab Runner ](https://docs.gitlab.com/runner/ ) take some
precautions to keep interactive web terminal data encrypted between them, and
everything protected with authorization guards. This is described in more
detail below.
- Interactive web terminals are completely disabled unless [`[session_server]`](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section) is configured.
2021-02-22 17:27:13 +05:30
- Every time the runner starts, it generates an `x509` certificate that is used for a `wss` (Web Socket Secure) connection.
2019-03-02 22:35:43 +05:30
- For every created job, a random URL is generated which is discarded at the end of the job. This URL is used to establish a web socket connection. The URL for the session is in the format `(IP|HOST):PORT/session/$SOME_HASH` , where the `IP/HOST` and `PORT` are the configured [`listen_address` ](https://docs.gitlab.com/runner/configuration/advanced-configuration.html#the-session_server-section ).
- Every session URL that is created has an authorization header that needs to be sent, to establish a `wss` connection.
- The session URL is not exposed to the users in any way. GitLab holds all the state internally and proxies accordingly.
2019-09-30 21:07:59 +05:30
## Enabling and disabling terminal support
2017-08-17 22:00:37 +05:30
2021-02-22 17:27:13 +05:30
NOTE:
2021-11-18 22:05:49 +05:30
AWS Classic Load Balancers (CLBs) do not support web sockets.
If you want web terminals to work, use AWS Network Load Balancers (NLBs).
2021-03-11 19:13:27 +05:30
Read [AWS Elastic Load Balancing Product Comparison ](https://aws.amazon.com/elasticloadbalancing/features/#compare )
2019-09-04 21:01:54 +05:30
for more information.
2017-08-17 22:00:37 +05:30
As web terminals use WebSockets, every HTTP/HTTPS reverse proxy in front of
2021-03-11 19:13:27 +05:30
Workhorse must be configured to pass the `Connection` and `Upgrade` headers
to the next one in the chain. GitLab is configured by default to do so.
2017-08-17 22:00:37 +05:30
2020-10-24 23:57:45 +05:30
However, if you run a [load balancer ](../load_balancer.md ) in
2017-08-17 22:00:37 +05:30
front of GitLab, you may need to make some changes to your configuration. These
guides document the necessary steps for a selection of popular reverse proxies:
2019-03-02 22:35:43 +05:30
- [Apache ](https://httpd.apache.org/docs/2.4/mod/mod_proxy_wstunnel.html )
- [NGINX ](https://www.nginx.com/blog/websocket-nginx/ )
2019-12-21 20:55:43 +05:30
- [HAProxy ](https://www.haproxy.com/blog/websockets-load-balancing-with-haproxy/ )
- [Varnish ](https://varnish-cache.org/docs/4.1/users-guide/vcl-example-websockets.html )
2017-08-17 22:00:37 +05:30
2021-02-22 17:27:13 +05:30
Workhorse doesn't let WebSocket requests through to non-WebSocket endpoints, so
2021-03-11 19:13:27 +05:30
it's safe to enable support for these headers globally. If you prefer a
narrower set of rules, you can restrict it to URLs ending with `/terminal.ws` .
This approach may still result in a few false positives.
2017-08-17 22:00:37 +05:30
If you installed from source, or have made any configuration changes to your
2019-07-07 11:18:12 +05:30
Omnibus installation before upgrading to 8.15, you may need to make some changes
2021-03-11 19:13:27 +05:30
to your configuration. Read
[Upgrading Community Edition and Enterprise Edition from source ](../../update/upgrading_from_source.md#nginx-configuration )
for more details.
2017-08-17 22:00:37 +05:30
2021-03-11 19:13:27 +05:30
To disable web terminal support in GitLab, stop passing
2017-08-17 22:00:37 +05:30
the `Connection` and `Upgrade` hop-by-hop headers in the *first* HTTP reverse
2021-02-22 17:27:13 +05:30
proxy in the chain. For most users, this is the NGINX server bundled with
2017-08-17 22:00:37 +05:30
Omnibus GitLab, in which case, you need to:
2019-03-02 22:35:43 +05:30
- Find the `nginx['proxy_set_headers']` section of your `gitlab.rb` file
- Ensure the whole block is uncommented, and then comment out or remove the
2017-08-17 22:00:37 +05:30
`Connection` and `Upgrade` lines.
For your own load balancer, just reverse the configuration changes recommended
by the above guides.
2021-02-22 17:27:13 +05:30
When these headers are not passed through, Workhorse returns a
2017-08-17 22:00:37 +05:30
`400 Bad Request` response to users attempting to use a web terminal. In turn,
2021-02-22 17:27:13 +05:30
they receive a `Connection failed` message.
2017-08-17 22:00:37 +05:30
## Limiting WebSocket connection time
2021-09-04 01:27:46 +05:30
By default, terminal sessions do not expire. To limit the terminal session
lifetime in your GitLab instance:
2017-08-17 22:00:37 +05:30
2021-11-11 11:23:49 +05:30
1. On the top bar, select **Menu > Admin** .
2021-09-04 01:27:46 +05:30
1. Select
[**Settings > Web terminal** ](../../user/admin_area/settings/index.md#general ).
1. Set a `max session time` .
