{"id":21293123,"url":"https://github.com/criteo/mesos-term","last_synced_at":"2025-10-29T10:21:37.006Z","repository":{"id":39386846,"uuid":"111217345","full_name":"criteo/mesos-term","owner":"criteo","description":"Web terminal and sandbox explorer for your mesos containers","archived":false,"fork":false,"pushed_at":"2023-03-29T18:06:39.000Z","size":2648,"stargazers_count":19,"open_issues_count":24,"forks_count":8,"subscribers_count":4,"default_branch":"master","last_synced_at":"2024-04-13T05:52:23.828Z","etag":null,"topics":["browser","cluster","containers","debug","debugger","hacktoberfest","interactive","mesos","sandbox","terminal","ucr","ui","web-debug"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/criteo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-11-18T15:42:24.000Z","updated_at":"2023-07-16T05:57:41.000Z","dependencies_parsed_at":"2023-02-04T07:01:26.475Z","dependency_job_id":"2cabcf3c-fa98-461c-8683-13bfd0f81e0d","html_url":"https://github.com/criteo/mesos-term","commit_stats":null,"previous_names":[],"tags_count":40,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/criteo%2Fmesos-term","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/criteo%2Fmesos-term/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/criteo%2Fmesos-term/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/criteo%2Fmesos-term/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/criteo","download_url":"https://codeload.github.com/criteo/mesos-term/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225741166,"owners_count":17516895,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["browser","cluster","containers","debug","debugger","hacktoberfest","interactive","mesos","sandbox","terminal","ucr","ui","web-debug"],"created_at":"2024-11-21T13:53:25.675Z","updated_at":"2025-10-29T10:21:31.982Z","avatar_url":"https://github.com/criteo.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MesosTerm\n\n**MesosTerm** is a web-based terminal for Mesos. It allows you to execute commands\nwithin Mesos containers (UCR only) from a web interface as you would do with\ndocker exec.\n\n![The interactive web terminal](doc/images/mesos-term.png?raw=true \"MesosTerm\")\n\n**WARNING**: you might face \"Connection has been closed.\" error messages randomly\nwhen using MesosTerm against Mesos version lower than 1.5.1. This is due to a\nrace condition mentioned in\n[MESOS-7742](https://issues.apache.org/jira/browse/MESOS-7742).\nThe solution is to upgrade Mesos to a version higher or equal to 1.5.1.\n\n## Features\n\n* Web-based container terminal.\n* Authentication against LDAP.\n* Authorizations based on Mesos labels.\n* Permissions delegation.\n\n## Getting started\n\nTo set up a complete environment for testing, ensure docker and docker-compose\nare installed on your machine and run:\n\n```\n./scripts/build.sh\n./scripts/tests/setup.sh\n```\n\nAnd then go to [http://localhost:3000](http://localhost:3000).\n\nTo get a task ID for running a terminal, you can get one from Marathon\navailable at [http://localhost:8080](http://localhost:8080). A few\napplications have already been created for you.\n\n![Retrieve Task ID](doc/images/task-id.png?raw=true \"TaskID\")\n\n## Use MesosTerm in production\n\nTo run MesosTerm in production you'll need to run the application\nwith several environment variables used to configure **MesosTerm**.\n\nWARNING: Make sure that access to the api/v1 endpoint of your Mesos cluster\nis authenticated by using the flag `--authenticate_http_readwrite`. Indeed, not\ndoing so could open serious security breaches and lead to privilege escalations.\n\n### Without authorizations\n\nIn order to use MesosTerm without authorizations, execute the following\ncommand:\n\n```\ndocker run --name mesos-term --rm -p 3000:3000 -it \\\n  -e MESOS_TERM_JWT_SECRET=your-jwt-secret \\\n  -e MESOS_TERM_MESOS_MASTER_URL=http://mesos-master:5050 \\\n  -e MESOS_TERM_MESOS_STATE_CACHE_TIME=60 \\\n  -e MESOS_TERM_NODE_ENV=production \\\n  -e MESOS_TERM_SESSION_SECRET=your-session-secret \\\n  clems4ever/mesos-term\n```\n\n### With authorizations\n\nIn order to use MesosTerm with authorizations, execute the following\ncommand:\n\n```\ndocker run --name mesos-term --rm -p 3000:3000 -it \\\n  -e MESOS_TERM_ENABLE_PER_APP_ADMINS=true \\\n  -e MESOS_TERM_ENABLE_RIGHTS_DELEGATION=true \\\n  -e MESOS_TERM_JWT_SECRET=your-jwt-secret \\\n  -e MESOS_TERM_LDAP_BASE_DN=dc=yourldap,dc=com \\\n  -e MESOS_TERM_LDAP_PASSWORD=the-admin-password \\\n  -e MESOS_TERM_LDAP_URL=ldap://yourldap.com \\\n  -e MESOS_TERM_LDAP_USER=cn=admin,dc=yourldap,dc=com \\\n  -e MESOS_TERM_MESOS_MASTER_URL=http://mesos-master:5050 \\\n  -e MESOS_TERM_MESOS_STATE_CACHE_TIME=60 \\\n  -e MESOS_TERM_NODE_ENV=production \\\n  -e MESOS_TERM_SESSION_SECRET=your-session-secret \\\n  -e MESOS_TERM_SUPER_ADMINS=admins,harry \\\n  clems4ever/mesos-term\n```\n\n### Connect to Mesos over https\n\nIn order to connect to Mesos over https, you need to provide the certificate that\nMesosTerm should trust using the MESOS_TERM_CA_FILE environment variable.\n\n```\ndocker run --name mesos-term --rm -p 3000:3000 -it \\\n  -v /path/to/my-ca.pem:/ca.pem \\\n  -e NODE_ENV=production \\\n  -e MESOS_TERM_CA_FILE=/ca.pem \\\n  -e MESOS_TERM_JWT_SECRET=your-jwt-secret \\\n  -e MESOS_TERM_MESOS_MASTER_URL=https://mesos-master:5050 \\\n  -e MESOS_TERM_MESOS_STATE_CACHE_TIME=60 \\\n  -e MESOS_TERM_SESSION_SECRET=your-session-secret \\\n  clems4ever/mesos-term\n```\n\n### Connect to an authenticated Mesos\n\nIn order to spawn a terminal, MesosTerm needs to query the api/v1 endpoint of Mesos.\nFor security reasons, this endpoint should ALWAYS be authenticated. You can use\nMESOS_TERM_MESOS_AGENT_PRINCIPAL and MESOS_TERM_MESOS_AGENT_PASSWORD to make MesosTerm\nauthenticate against the Mesos agent in order to run a terminal.\n\nFor instance,\n\n```\ndocker run --name mesos-term --rm -p 3000:3000 -it \\\n  -e NODE_ENV=production \\\n  -e MESOS_TERM_JWT_SECRET=your-jwt-secret \\\n  -e MESOS_TERM_MESOS_MASTER_URL=https://mesos-master:5050 \\\n  -e MESOS_TERM_MESOS_STATE_CACHE_TIME=60 \\\n  -e MESOS_TERM_SESSION_SECRET=your-session-secret \\\n  -e MESOS_TERM_MESOS_AGENT_PRINCIPAL=mesosterm \\\n  -e MESOS_TERM_MESOS_AGENT_PASSWORD=the_password \\\n  clems4ever/mesos-term\n```\n\n\n\n## Option details\n\nHere are the details of available options.\n\n| Parameter                               | Description                                                                              |\n|-----------------------------------------|------------------------------------------------------------------------------------------|\n| MESOS\\_TERM\\_COMMAND                    | The command to be run in the container when a user logs in. (Default: /bin/sh)           |\n| MESOS\\_TERM\\_ENVIRONMENT                | List of environment variable to enrich the shell with (NAME=value, colon separated)      |\n| MESOS\\_TERM\\_ENABLE\\_PER\\_APP\\_ADMINS   | If 'true', application administrators can be declared with the Mesos label MESOS\\_TERM\\_DEBUG\\_GRANTED\\_TO label. It means those users can log into the application containers. An example is provided below. (Default: false) |\n| MESOS\\_TERM\\_ALLOWED\\_TASK\\_ADMINS      | White list of application administrators (users or groups) allowed to override application configuration through Mesos label |\n| MESOS\\_TERM\\_ENABLE\\_RIGHTS\\_DELEGATION | If 'true', users with access can delegate rights to log into one specific container to one person for a certain amount of time. (Default: false) |\n| MESOS\\_TERM\\_JWT\\_SECRET                | Secret used to generate and validate JWT tokens.                                         |\n| MESOS\\_TERM\\_LDAP\\_BASE\\_DN             | Base distinguished name from which to search users for authentication.                   |\n| MESOS\\_TERM\\_LDAP\\_PASSWORD             | Password of the LDAP user to bind against LDAP server.                                   |\n| MESOS\\_TERM\\_LDAP\\_URL                  | Url of the LDAP server. Authorizations are disabled if this env variable is not set.     |\n| MESOS\\_TERM\\_LDAP\\_USER                 | User DN of the LDAP user to bind against LDAP server.                                    |\n| MESOS\\_TERM\\_MESOS\\_MASTER\\_URL         | Url of the Mesos master to fetch the state from.                                         |\n| MESOS\\_TERM\\_MESOS\\_MASTER\\_STATE\\_PATH | Path leading to the state file on the master. (default: /master/state)                   |\n| MESOS\\_TERM\\_MESOS\\_AGENT\\_SSL          | Whether to use SSL to reach the agents. (default: is same as in master url)              |\n| MESOS\\_TERM\\_MESOS\\_STATE\\_CACHE\\_TIME  | Time in seconds before invalidating the cache containing Mesos state.                    |\n| MESOS\\_TERM\\_NODE\\_ENV                  | Must be \"production\" for express to run in production mode.                              |\n| MESOS\\_TERM\\_SESSION\\_SECRET            | Secret used to encrypt session cookie.                                                   |\n| MESOS\\_TERM\\_SESSION\\_MAX_AGE_SEC       | The session cookie will expire after this amount of time. (default: 3h)                  |\n| MESOS\\_TERM\\_SUPER\\_ADMINS              | Comma-separated list of LDAP users and groups having all rights on all containers.       |\n| MESOS\\_TERM\\_CA\\_FILE                   | CA file to connect to Mesos agent  in pem format.                                        |\n| MESOS\\_TERM\\_MESOS\\_AGENT\\_PRINCIPAL    | The principal Mesos term uses to connect to the Mesos agent.                             |\n| MESOS\\_TERM\\_MESOS\\_AGENT\\_PASSWORD     | The password Mesos term uses to connect to the Mesos agent.                              |\n| MESOS\\_TERM\\_AUTHORIZE\\_ALL\\_SANDBOXES  | If `true`, all authenticated users can read all sandboxes. Otherwise the permissions are granted according to the same strategy as for terminals   |\n\n## Authorizations model\n\n**MesosTerm** support a two-level authorization model allowing certain users\nto be super administrator, meaning users able to debug any container in Mesos,\nand other users considered as application administrators who can only debug\ntheir own applications.\n\n### Super administrators\n\nSuper administrators must be mentionned in the MESOS\\_TERM\\_SUPER\\_ADMINS\nenvironment as a comma-separated list of LDAP users and/or groups. They have\nfull permissions in MesosTerm, i.e., they are able to debug any container\nbe it root or not. They are also able to produce access tokens to delegate\nrights to log into a container.\n\n### Application administrators\n\nApplication administrators are able to debug their own applications and\ntherefore they must be mentionned as a comma-separated list of LDAP users\nand groups in the MESOS\\_TERM\\_DEBUG\\_GRANTED\\_TO task labels. Here is an\nexample using Marathon.\n\n![authorized users](doc/images/authorizations.png?raw=true \"Authorizations\")\n\nIf needed, an optional layer of security can be added by using the MESOS\\_TERM\\_ALLOWED\\_TASK\\_ADMINS\nparameter. This is a comma-separated whitelist of users/groups allowed to use the\nMESOS\\_TERM\\_DEBUG\\_GRANTED_TO label in their Mesos applications. If empty, all users/groups\nare allowed to use the label.\n\nFor security reasons, it has been decided to not allow administrators of an application\nto log in a container in the case the Mesos task runs as `root` or no user\n(meaning the user running Mesos, i.e., most probably `root`). Only super\nadministrators can debug those containers.\n\n### Permissions delegation\n\nIn some cases, super administrators might want to allow access to a\nspecific container to a user for a certain amount of time. This is possible\nin MesosTerm by producing an access token and giving it to the delegated user.\nHe will then be able to access this specific container for the time provided.\n\nThe access delegation is only available to super admins via the button called\n`Grant access` in the UI or via the endpoint /delegate.\n\n![access delegation](doc/images/grant-access.png?raw=true \"Access Delegation\")\n\n## Mesos state caching\n\nFor huge production Mesos clusters, it might be slow to retrieve the Mesos state\nand get the task information in order to verify the permissions of a user\nto log into a container. In order to improve the user experience,\nthe Mesos state is fetched regularly and cached. The cache is invalidated\nafter some time defined by the environment variable called\nMESOS\\_TERM\\_MESOS\\_STATE\\_CACHE\\_TIME and expressed in seconds.\n\nYou can set a big number in order to reduce the load of your Mesos cluster.\nThough, it is important to know that **MesosTerm** automatically invalidate\nthe cache when a terminal is requested for a task that does not exist in\nthe cache. It allows users to log into newly created instances that\nmight not be yet in the cache.\n\n## Contributing\n\nMesosTerm uses hot-reloading to let you develop and test easily. In order\nto spawn a complete environment please follow the steps:\n\n    $ # Prepare the environment\n    $ source bootstrap.sh\n\n    $ # Run the suite called \"standard\"\n    $ ./tests/resources/setup.sh standard\n\nA suite represents a complete environment for a given configuration of\nMesosTerm. For instance, in a given configuration, authorization module\ncould be enabled while disabled in another configuration.\n\nThe list of available suite is:\n\n- noadmin / task admins are disabled, only super admins can have access to containers.\n- noauth / authentication and authorization is completely disabled.\n- standard / authentication and authorization is enabled with standard features.\n- taskadmins / task admins are enabled to restrict the set of administrators of tasks (see MESOS\\_TERM\\_ALLOWED\\_TASK\\_ADMINS above).\n\nYou can then run the corresponding set of tests once you're happy with you changes with\n\n    $ ./tests/resources/run_tests standard\n\nEnjoy!\n\n## License\n**MesosTerm** is **licensed** under the **[MIT License]**. The terms of the license are as follows:\n\n    The MIT License (MIT)\n\n    Copyright (c) 2016 - Clement Michaud\n\n    Permission is hereby granted, free of charge, to any person obtaining a copy\n    of this software and associated documentation files (the \"Software\"), to deal\n    in the Software without restriction, including without limitation the rights\n    to use, copy, modify, merge, publish, distribute, sublicense, and/or sell\n    copies of the Software, and to permit persons to whom the Software is\n    furnished to do so, subject to the following conditions:\n\n    The above copyright notice and this permission notice shall be included in\n    all copies or substantial portions of the Software.\n\n    THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\n    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\n    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\n    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,\n    WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN\n    CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.\n\n[MIT License]: https://opensource.org/licenses/MIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcriteo%2Fmesos-term","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcriteo%2Fmesos-term","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcriteo%2Fmesos-term/lists"}