{"id":14965819,"url":"https://github.com/erwindon/saltgui","last_synced_at":"2025-05-15T12:05:02.267Z","repository":{"id":38048874,"uuid":"63809265","full_name":"erwindon/SaltGUI","owner":"erwindon","description":"A web interface for managing SaltStack based infrastructure.","archived":false,"fork":false,"pushed_at":"2025-05-07T04:30:32.000Z","size":5230,"stargazers_count":561,"open_issues_count":9,"forks_count":48,"subscribers_count":23,"default_branch":"master","last_synced_at":"2025-05-09T08:58:39.323Z","etag":null,"topics":["es6","eslint","front-end","frontend","html","html-css","html5","javascript","js","minions","pam","salt","salt-command","webapp","yarn"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/erwindon.png","metadata":{"files":{"readme":"docs/README.md","changelog":null,"contributing":"docs/CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2016-07-20T19:40:50.000Z","updated_at":"2025-05-08T20:47:58.000Z","dependencies_parsed_at":"2023-12-13T20:11:35.105Z","dependency_job_id":"765ecb3a-1442-4968-8819-2417290ec381","html_url":"https://github.com/erwindon/SaltGUI","commit_stats":{"total_commits":1838,"total_committers":17,"mean_commits":"108.11764705882354","dds":0.2138193688792165,"last_synced_commit":"dba5b725c16f448248fbc715edd09bd7a21fb927"},"previous_names":[],"tags_count":42,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erwindon%2FSaltGUI","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erwindon%2FSaltGUI/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erwindon%2FSaltGUI/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/erwindon%2FSaltGUI/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/erwindon","download_url":"https://codeload.github.com/erwindon/SaltGUI/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254337612,"owners_count":22054253,"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":["es6","eslint","front-end","frontend","html","html-css","html5","javascript","js","minions","pam","salt","salt-command","webapp","yarn"],"created_at":"2024-09-24T13:35:22.744Z","updated_at":"2025-05-15T12:04:57.251Z","avatar_url":"https://github.com/erwindon.png","language":"JavaScript","readme":"# SaltGUI\n\nSaltGUI is an open source web interface for managing a SaltStack server and its minions. Built using vanilla ES6 and implemented as a wrapper around the rest_cherrypy server a.k.a. salt-api.\n\nThe version tagged `release` is the latest released version. The version `master` should be fine, but it may contain changes that are not yet in these release-notes.\n\nSee [SaltGUI documentation](https://erwindon.github.io/SaltGUI/) for the complete documentation.\n\nIMPORTANT: since Salt version 3006, it is needed to add the configuration option `netapi_enable_clients` to allow salt-api - and thus SaltGUI - to work. See also [netapi-enable-clients.html](https://docs.saltproject.io/en/latest/topics/netapi/netapi-enable-clients.html#netapi-enable-clients). Additionally, any Python\npackages that the SaltStack installation also depends on, must be installed with `salt-pip`. This includes authentication plugins\nsuch as `yubico_client`, or execution modules such as `boto3_sns`.\n\nIMPORTANT: The SaltGUI team can only support SaltStack versions 3006 and higher. Versions before that are no longer published by the SaltStack team.\nThat makes it very hard to perform proper testing for SaltGUI releases.\nWe suggest to upgrade the SaltStack installation when you are still using a version that is older than that.\n\n[![CodeQL](https://github.com/erwindon/SaltGUI/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/erwindon/SaltGUI/actions/workflows/codeql-analysis.yml)\n\n## Screenshots\n![overview](screenshots/overview.png)\n\n![job](screenshots/job.png)\n\n\n## Features\n- Simple setup without the need to add a database\n- Login via PAM or any other supported authentication by Salt\n- View minions and easily copy IPs\n- Run state.highstate for a particular minion or all\n- View the seven most recent jobs run on Salt\n- Manually run any Salt function and see the output\n- View highstate for all minions with details\n- View issues for all minions with trivial solutions\n- View the values for grains for a particular minion\n- View the schedules for a particular minion\n- View the values for pillars for a particular minion\n- View the beacons for a particular minion\n- View the live events on the salt-event bus\n- View internal documentation for any salt command\n- View external documentation for any salt command\n- View minions organized by node-group\n- View details optionally in a separate windows\n- Define your own custom documentation for commands\n- Match list of minions against reference list\n- Match status of minions against reference list\n- Keyboard control for top-level navigation\n- Keyboard control to apply templates\n- Choose between live info and cached info for grains/pillar\n- View details of orchestrations and allow to start them\n\n\n## Quick start using PAM as authentication method\n- Install `salt-api` - this is available in the Salt repo which should already be known if you're using Salt\n- Open the master config /etc/salt/master\n- Find `external_auth` and configure as following (see the note below!):\n\n```\nexternal_auth:\n    pam:\n        saltuser1:\n            - .*\n            - '@runner'\n            - '@wheel'\n            - '@jobs'\n\n# for SaltStack 3006 and higher\nnetapi_enable_clients:\n    - local\n    - local_async\n    - runner\n    - wheel\n```\n\n- See [Permissions](PERMISSIONS.md) for more restricted security configurations.\n- The username 'saltuser1' is only an example. Generic accounts are not recommended, use personal accounts instead. Or use a user-group, see [EAUTH](https://docs.saltproject.io/en/latest/topics/eauth/index.html) for details.\n- Multiple entries like `saltuser1` can be added when you have multiple users.\n- `saltuser1` is a unix (PAM) user, make sure it exists or create a new one.\n- At the bottom of this file, also setup the rest_cherrypy server to access SaltGUI from \"http://localhost:3333\" (or on any of the hostnames that the server has):\n\n```\nrest_cherrypy:\n    port: 3333\n    host: 0.0.0.0\n    disable_ssl: true\n    app: /srv/saltgui/index.html\n    static: /srv/saltgui/static\n    static_path: /static\n```\n\n- Note that the cherrypy server is part of the salt-api package and has no separate installation. It is configured using the master configuration file. When configured using the above configurations, both the api calls and the html/js files are served by the cherrypy server. Therefore no additional web application server is needed.\n- Note that from the SaltGUI GIT repository, only the directory `saltgui` forms the actual SaltGUI web application.\n- Replace each of the `/srv/saltgui` in the above config with the actual `saltgui` directory from the GIT repository. Alternatively, you can create a soft-link /src/saltgui that points to the actual saltgui directory.\n- To successfully use `salt-api` with a default PAM setup, if may be needed to grant read access on `/etc/shadow` to the `salt` user. This is best done using `sudo usermod --append --groups shadow salt`.\n- Restart everything with ``pkill salt-master \u0026\u0026 pkill salt-api \u0026\u0026 salt-master -d \u0026\u0026 salt-api -d``\n- You should be good to go. If you have any problems, open a GitHub issue. As always, SSL is recommended wherever possible but setup is beyond the scope of this guide.\n\n**Note: With this configuration, the user has access to all salt modules available, maybe this is not what you want**\n\nPlease read [Permissions](PERMISSIONS.md) for more information.\n\n\n## Authentication\nSaltGUI supports the following authentication methods supported by salt:\n- pam\n- file\n- ldap\n- mysql\n- yubico\n\nSince pam by itself is already very powerfull, that one is mentionned as standard.\nBy default, it provides access to the Linux password file.\nWhen other authentication methods need to be used, their names can be added to file `saltgui/static/salt-auth.txt`.\nThere is one name per line in that file. Choose the authentication methods that are activated\nin the salt-master configuration wisely, as the integrity of the salt-master and all salt-minions depends on it.\n\nWhen a line `CLEAR` is present in the configuration file, then only the methods listed in the configuration file\nare shown. When only one method is listed, the corresponding dropdown-box will not be visible on the login panel.\nIn that case, that method will always be used.\n\nNote that SaltGUI cannot inspect the `master` file to see which authentication methods are actually in use.\nThis is because the salt-api can only read the file after login.\n\nNote that adding the `rest` authentication method in configuration section `external_auth` forces the parameter `keep_acl_in_token` to become `true`.\nThat again changes the behavior of the other authentication methods and may lead to unexpected authentication problems.\n\nWhen the file is absent or empty, the defaults apply.\nUse an empty file to prevent the otherwise harmless [404](https://www.wikipedia.org/wiki/HTTP_404) error.\n\nSee the [EAUTH documentation](https://docs.saltstack.com/en/latest/topics/eauth/index.html) and the [Salt auth source code](https://github.com/saltstack/salt/tree/master/salt/auth) for more information.\n\n\n## Browser tabs\nSaltGUI is a single page web-application.\nIn cases where you would zoom in on details, it is possible to open a new browser tab with the requested details.\nUse CTRL-click to open the page in a new tab.\nUse ALT-click to open the page in a new tab and also make that the current tab.\nThis works for clicks on table-rows and for clicks on popup-menu items.\nThese functions are a bit browser-dependent, but all major browsers seem to follow this behavior.\nWhen a new tab is opened by SaltGUI, it does not contain the menu bar items, secondary panels or a close-button inside the page.\n\n\n## Command Box\nSaltGUI supports entry of commands using the \"command-box\". Click on `\u003e_` in the top right corner to open it.\n\nEnter `salt-run` commands with the prefix `runners.`. e.g. `runners.jobs.last_run`. The target field can remain empty in that case as it is not used.\n\nEnter `salt-call` commands with the prefix `wheel.`. e.g. `wheel.key.finger`. The target field will be added as named parameter `target`. But note that that parameter may not actually be used depending on the command.\n\nEnter regular commands without special prefix. e.g. `test.ping`. The command is sent to the minions specified in the target field.\n\nThe text `##connected` in the target field will be immediatelly replaced by the list of connected\nminions, or with `*` when all minions are connected, or with an expression when that is shorter.\n\nCommands can be run normally, in which case the command runs to completion and shows the results. Alternatively, it can be started asynchronously, in which case only a bit of progress information is shown. When variable `state_events` is set to `true`, then the progress is shown per state when applicable. Batch commands are not supported at this time.\n\nWhen executing commands, the setting for api-flag `full_return` is taken from option `saltgui_full_return` in salt master configuration file `/etc/salt/master`.\nWhen set to `true`, this will result in some more information available in the execution result, e.g. the job-id.\nThis flag may (or may not) be applied to the internal commands that SaltGUI uses to show information.\n\n\n## Output\nSaltGUI shows the data that is returned by the Salt API.\nSome variation can be achieved by modifying salt master configuration file `/etc/salt/master`.\ne.g. (the default)\n```\nsaltgui_output_formats: doc,saltguihighstate,json\n```\n`doc` allows reformatting of documentation output into more readable format. Also implies that only the result from one minion is used.\n`saltguihighstate` allows reformatting of highstate data in a sorted and more readable format.\n`json`, `yaml` and `nested` specify how all other output should be formatted. Only the first available of these formats is used.\n\n\n## Time representation\nThe time formats used by Salt are very detailed and by default have 6 decimal digits to specify as accurate as nano-seconds. For most uses that is not needed. The fraction can be truncated to less digits by modifying salt master configuration file `/etc/salt/master`.\ne.g.\n```\nsaltgui_datetime_fraction_digits: 3\n```\nThe value must be a number from 0 to 6.\nNote that the effect is achieved by string truncation only. This is equivalent to always rounding downwards.\n\nHow the date and times that are shown can also be changed.\ne.g.:\n\n```\nsaltgui_datetime_representation: utc\n```\nThe value must be `utc`, `local`, `utc-localtime` or `local-utctime`.\nWith `utc`, only the UTC date and time are shown.\nWith `local`, only the local date and time are shown. This includes an indication of the timezone.\nWith `utc-localtime`, the UTC date and time are shown. Additionally, the local time (not the local date) is shown.\nWith `local-utctime`, the local date and time are shown. Additionally, the UTC time (not the UTC date) is shown.\nIn all cases, a tooltip is added to a date+time field that shows the full representation of the date and time in both the local timezone and in UTC.\n\nWhen using very old browsers, the required date/time functions may not be present. In that case SaltGUI reverts to simply displaying the reported time from the Salt system. The tooltip is then not shown.\n\n\n## Templates\nSaltGUI supports command templates for easier command entry into the command-box.\nThe menu item for that becomes visible there when you define one or more templates\nin salt master configuration file `/etc/salt/master`.\nThe field `targettype` supports the values `glob`, `list`, `compound` and `nodegroup`.\nEntries will be sorted in the GUI based on their key.\nYou can leave out any detail field.\ne.g.:\n```\nsaltgui_templates:\n    template1:\n        description: First template\n        target: \"*\"\n        command: test.fib num=10\n        key: \"f\"\n    template2:\n        description: Second template\n        targettype: glob\n        target: dev*\n        command: test.version\n```\n\nWhen there are a lot of templates, they can be organized into categories.\ne.g.:\n```\nsaltgui_templates:\n    template1:\n        description: First template\n        target: \"*\"\n        command: test.fib num=10\n        category: cat1\n    template2:\n        description: Second template\n        targettype: glob\n        target: dev*\n        command: test.version\n        categories:\n            - cat1\n            - cat2\n```\nWhen at least one template is assigned to a category, then you can select a template category before\nselecting the actual category. Otherwise that choice remains hidden. Templates can be in multiple categories\nwhen a list of categories is assigned.\n\nWhen a key is assigned to a template, then you can activate a template by typing that key\nwhile using any screen in SaltGUI. Only keys that can be typed without shift/alt/ctrl are useable.\n\n\n## Jobs\nSaltGUI shows a maximum of 7 jobs in on the right-hand-side of the screen.\nSaltGUI shows a maximum of 50 jobs on the dedicated jobs page.\nCommands that are used internally in SaltGUI are initially hidden.\n\nOn the Jobs page, more jobs can be made visible.\nSelect `Show eligible jobs` to show all jobs that are not classified as internally-used jobs.\nSelect `Show all jobs` to show all jobs that are known to salt.\n\nAdditional commands to hide can be configured\nin salt master configuration file `/etc/salt/master`.\ne.g.:\n```\nsaltgui_hide_jobs:\n    - test.ping\n```\n\nCommands that are normally hidden can be made visible using configuration\nin salt master configuration file `/etc/salt/master`.\ne.g.:\n```\nsaltgui_show_jobs:\n    - grains.items\n```\n\n\n## Grains\nSelected grains can be previewed on the Grains page.\nThe names of these grains can be configured\nin salt master configuration file `/etc/salt/master`.\ne.g.:\n```\nsaltgui_preview_grains:\n    - \"osrelease_info\"\n```\nThe names can be specified as simple names like the example above.\nAlternatively, the [grains.get](https://docs.saltstack.com/en/latest/ref/modules/all/salt.modules.grains.html#salt.modules.grains.get) notation can be used to get more detailed information. The separator is always `:`. e.g. `locale_info:timezone`.\nAlternatively, the [jsonpath](https://www.w3resource.com/JSON/JSONPath-with-JavaScript.php) notation can be used to allow even more freedom. Jsonpath is used when the text starts with a `$`. e.g. `$.ip4_interfaces.eth0[0]`.\n\nThe configured value can be prefixed with a title and an '=' sign to specify the title to be used on the screen.\ne.g. `IP-Number=$.ip4_interfaces.eth0[0]` shows `IP-Number` as title, but uses the value `$.ip4_interfaces.eth0[0]` for each minion.\nNote that when the value somehow contains an '=' sign, then a title must be provided to prevent confusion.\n\nIn any table where the the minion status is shown and where the grain-values of the minion are also known, the minion status is\nreplaced with the the best value from grain `fqdn_ip4`.\nThe best value is chosen by first eliminating all values that appear for more than one minion.\nThen the first value that has the most specific network prefix is used.\nIt is possible to chose a different grain by setting variable `saltgui_ipnumber_field` in salt master configuration file `/etc/salt/master`.\nIt is possible to restrict the eligible IP-numbers by setting variable `saltgui_ipnumber_prefix` in salt master configuration file `/etc/salt/master`. Only values with that string-prefix are considered. You can specify several prefixes, for example:\n```\nsaltgui_ipnumber_prefix:\n    - 192.168\n    - 10.10\n```\nThe display of the IP-numbers can simply be disabled by choosing a non-existing grain or by choosing a non-existing prefix.\n\nSaltGUI will retrieve cached grains information when variable `saltgui_use_cache_for_grains` is set to `true`.\nIn that case, unreachable minions will appear without warnings for that.\nIn all cases, the information may be less accurate.\nA warning for offline minions is only shown on the Minions panel.\n\n## Pillars\nPillars potentially contain security senstitive information.\nTherefore their values are initially hidden.\nValues become visible by clicking on them.\nThis behavior can be changed by adjusting the values of the configuration\nin salt master configuration file `/etc/salt/master`.\nThe values for the pillar whose name match one of these regular expressions\nare initially shown.\ne.g.:\n```\nsaltgui_public_pillars:\n    - pub_.*\n```\n\nSaltGUI will retrieve cached pillar information when variable `saltgui_use_cache_for_pillar` is set to `true`.\nIn that case, unreachable minions will appear without warnings for that.\nIn all cases, the information may be less accurate.\nA warning for offline minions is only shown on the Minions panel.\n\n## Nodegroups\nThe Nodegroups page shows all minions, but groups the minions by their nodegroup.\nSince the group membership can only (reliably) be determined by executing salt commands, the overview takes some time to build.\nWhen a minion happens to be a member of multiple nodegroups, then a row for that minion will appear mutiple times in the overview.\nWhen using targeting based on nodegroups, the salt-system does not filter out the non-accepted minions.\nTherefore also the rejected, denied and unaccepted minions will show up.\nEven the minion names that are in the nodegroup, but which do not actually exist, will show up as 'unknown'.\n\n## Highstate\nThe Highstate page provides an overview of the minions and their latest state information.\nAt most `saltgui_max_show_highstates` (10 if not set) highstate jobs (`state.apply` or `state.highstate`) are considered.\n\nMore than `saltgui_max_highstate_states` (20 if not set) of states switches to summary from detailed view.\n\nIndividual low-states can be re-tried by clicking on their state symbol.\nNote that since the output of the `state.sls_id` commands is not considered in this overview,\nthe result of such action has no effect on this screen.\nUse `state.apply test=true` to update the information without making changes on the minions.\n\nFor organisations where the 'saltenv' facility is used, it is possible to limit the jobs that are\nconsidered to include (or exclude) only specific saltenvs.\ne.g.:\n```\nsaltgui_show_saltenvs:\n    - base\n```\nor\n```\nsaltgui_hide_saltenvs:\n    - env2\n    - env3\n```\nTypically only one of these variables should be set.\nJobs that were started without the `saltenv` parameter are, for this purpose only, assumed to use the value `default` for this parameter. This allows these jobs to be hidden/showed using the same mechanism. SaltGUI does not replicate the internal logic of the salt-master and/or the salt-minion to determine which saltenv would actually have been used for such jobs.\n\n## Orchestrations\nThe Orchestrations page shows the available orchestrations with their steps. Name, target and function are listed in separate columns.\nAll other details will be visible in the details column. The steps are listed in priority order.\nBut note that additional dependencies may cause an alternative execution sequence.\n\nIn the configuration files, SaltStack does not clearly distingish between state-configuration and orchestration-configuration.\nSaltGUI only shows information that has the orchestration format.\n\nAn orchestration can be executed or tested. The output resembles the output of highstate commands, but now each step is a whole salt command instead of a state.\nSince the orchestration is run by the salt-master, the results are organized for only this host.\nNote that SaltStack uses a slightly different minion-name for that.\n\nNote that each stage is started as a separate job. Neither SaltStack, nor SaltGUI, has information available to somehow group the results.\n\nUnlike the highstate system, there are no events available in the SaltStack that can be used to track the progress of an orchestration.\n\n## Issues\nThe Issues page provides an overview of the system and reports any issues.\nWhen no issues are found, the list remains empty.\nThe following issues may be reported:\n* Disabled beacons, either individually disabled or on minion level\nthis should be solved by enabling or removing that beacon.\n* Jobs that are still running after 60 seconds\nthis should be solved by terminating the job or just let it finish.\n* Unaccepted keys\nthis should be solved by accepting or rejecting that key.\n* Unconnected minions\nthis should be solved by fixing the minion, the minion's host or the connection to that host.\n* Disabled schedules, either individually disabled or on minion level\nthis should be solved by enabling or removing that schedule.\n* States that contain one or more failed tasks\nthis should be solved by retrying that state. Note that only all tasks of that state can be retried together.\n\nEach issue has its own dropdown-menu, which typically contains:\n* One or more salt-commands to fix the situation;\nBut note that there might be more possible solutions, some of which may actually be more preferred.\n* A navigation-command to go to a page for more details.\n\n## Command documentation\n\n### Internal documentation\nWhen at least a part of a command is entered, the documentation will have a menu item to run a salt command that collects the internal documentation.\nWhen the target field is still empty, all minions are asked to produce the documentation.\nOtherwise the given target is used. When using identical minions, there is not much difference, but with minions on different operating systems,  this helps to get the best matching documentation.\nAlthough multiple minions may return the documentation, only the first answer is actually presented.\nWhen some minions are offline, it may be useful to specify a target that does not include the offline minions, e.g. by specifying a single minion that is known to be online.\n\n### External documentation\nWhen the function \"Online reference for ...\" is used, a set of URLs is produced. The URLs point to the SaltStack documentation on the `docs.saltproject.io` website.\nWhen more parts of the command are already typed in, then more specific URLs become available.\nThis function does not execute a command to any minion.\nWhen the command-box is opened for the first time, a list of command-providers is retrieved from all minions to determine which providers (categories) are available.\nAn alternative target can be specified in the configurationfile for retrieving the list.\n\nTo skip retrieving this information, use value `SKIP`.\n```\ntest_providers_target: \"SKIP\"\n```\n\nTo specify an alternative target to retrieve this information, use any other value.\nThis may be single minion-id, or any other minion pattern.\nThe target-type is automatically decided, just like in the \"Target\" field.\n```\ntest_providers_target: \"minion7\"\n```\n\n### Custom command documentation\nA custom HTML help text can be shown from the \"Manual Run\" overlay.\n\nTo use it,\n- specify `saltgui_custom_command_help` in the salt master config. Example:\n```\nsaltgui_custom_command_help: |\n    \u003ch2\u003eJob Commands\u003c/h2\u003e\n        runners.jobs.active\n        =\u003e Show active jobs\n\n        runners.jobs.list_job «JID»\n        =\u003e Show job with given job id (JID)\n```\n- Hover the documentation icon (`📖︎`) near the command input field and select `Show custom help`\n\n\n## Message-of-the-day\nA message-of-the-day (motd) can be added to the login screen.\nIt can be used for any information, e.g.:\n- legal statement\n- system identification\n- useful links to other systems\n- informing users about system availability\n- etc.\n\nThe text is stored in file `saltgui/static/salt-motd.txt` or `saltgui/static/salt-motd.html`.\nThe first must be pre-formatted text only. The second one can contain full HTML text. Both are shown when they are present.\nWhen the files are absent or empty, no message is shown.\nUse empty files to prevent the otherwise harmless [404](https://www.wikipedia.org/wiki/HTTP_404) error.\nNote that the message should not contain sensitive data, as its content is shown before logging in.\n\nAlternatively, or additionally, the text can be retrieved from the `master` file entries `saltgui_motd_txt` and `saltgui_motd_html`. These entries can contain sensitive information because its content can only be retrieved after login. But it is still recommended to not let the text contain any sensitive data.\n\n\n## Multi master setup\nWhen multiple salt-masters are in use in a multi-master setup, an installation of salt-api is needed per salt-master. And SaltGUI must have an installation per salt-api installation.\nNo specific extra configuration is needed for SaltGUI in this scenario.\nBut note that SaltGUI cannot bypass the restrictions that are implied by a multi-master setup.\ne.g. each salt-master only holds the job history of the jobs that are initiated from that salt-master.\nFor multi-master setup, see also [Multi Master tutorial](https://docs.saltproject.io/en/latest/topics/tutorials/multimaster.html).\n\n\n## Reduced menus\nWhen apis are disabled using the native `external_auth` mechanism,\nSaltGUI may show menu-items that have become unuseable.\nIn that case, it may be useful to reduce the menu-bar to less items.\nVariable `saltgui_pages` is read from salt master configuration file `/etc/salt/master`.\nIt contains the list of accessible pages per user.\nThe first page in the list also becomes the landing page.\nUsers that are not listed still have the full menu.\ne.g.:\n```\nsaltgui_pages:\n    user1:\n        - keys\n        - grains\n```\nNote that this is NOT a security mechanism to reduce what a user can do.\nAll pages are still accessible using their original deep-link.\nAnd also any command can still be issued using the command-box.\nFor real security measures, use parameter `external_auth`.\n\n\n## Performance\nSaltGUI does not have artificial restrictions.\nBut displaying all data may be slow when there is a lot of data.\nMost notorious is the display of a highstate with hundreds of minions, each with douzens of states.\nSaltGUI can be forced to use a slightly simpler output by setting a parameter in salt master configuration file `/etc/salt/master`.\ne.g.:\n```\nsaltgui_tooltip_mode: simple\n```\nThis parameter forces SaltGUI to use a very simple tooltip representation.\nThis is then the built-in version from the brower.\nTypical effect is that it is shown slightly delayed and that is looks a bit primitive.\nThe only other allowed value is \"none\", with the effect that no tooltips are shown at all.\n\n\n## Settings and statistics\nBy using ctrl-click on the SaltGUI logo in the top-left corner, an otherwise hidden page is made visible. The page shows the relevant settings from 3 categories on the left side and the api statistics on the right side.\n\nFirst category contains the \"session\" details, which are the result of the login.\nSecond category contains the variables from the master file that are also relevant for SaltGUI.\nThe final category contains the variables that are specific to SaltGUI.\nSimple variables with a limited range of values can be changed here for the duration of the current session. Permanent changes must be made in the master file.\n\nThe statistics panel is updated every 3 seconds.\nNumeric fields that are known to contain timestamps are reformatted as readable strings.\nNumeric fields that are known to contain durations are reformatted as readable strings.\nStatistics for most threads that did not handle any requests yet are replaced by an empty string.\nThe amount of details shown depends on the parameter `collect_stats` in the `rest_cherrypy` block of the master file.\n\n\n## Key administration\nIn situations like cloud hosting, hosts may be deleted or shutdown frequently.\nBut Salt remembers the key status from both.\nSaltGUI can compare the list of keys against a reference list.\nThe reference list is maintained as a text file, one minion per line.\nFirst column is the minion name.\nSecond column is `false` when the minion is known to be absent due to machine shutdown.\nIt should be `true` otherwise.\nWhen the second column is missing, this validation is not performed.\nLines starting with `#` are comment lines.\nThe filename is `saltgui/static/minions.txt`.\nDifferences with this file are highlighted on the Keys page.\nMinions that are unexpectedly down are highlighted on the Minions page.\nWhen the file is absent or empty, no such validation is done.\nUse an empty file to prevent the otherwise harmless [404](https://www.wikipedia.org/wiki/HTTP_404) error.\nIt is suggested that the file is generated from a central source,\ne.g. the Azure, AWS or similar cloud portals; or from a company asset management list.\n\n\n## Separate SaltGUI host\nIn some specific environments you might not be able to serve SaltGUI directly from salt-api.\nIn that case you might want to configure a web server (for example NGINX) to serve SaltGui\nand use it as proxy to salt-api so that requests are answered from the same origin from the browser point of view.\n\nSample NGINX configuration might look like this:\n```\nserver {\n    listen       80;\n    server_name  _;\n    root         /data/www;\n    index        index.html;\n\n    # handle internal api (proxy)\n    location /api/ {\n        proxy_set_header X-Real-IP $remote_addr;\n        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;\n        proxy_set_header X-NginX-Proxy true;\n        proxy_pass http://saltmaster-local:3333/;\n        proxy_ssl_session_reuse off;\n        proxy_set_header Host $http_host;\n        proxy_redirect off;\n    }\n\n    # handle saltgui web page\n    location / {\n        try_files $uri /index.html;\n    }\n}\n```\n\nThe value of the `API_URL` in the `config.js` file must point to path where salt-api is exposed.\nThe value of the `NAV_URL` in the `config.js` file must point to path where the SaltGUI application is exposed.\n```\nconst config = {\n    API_URL: '/api',\n    NAV_URL: '/app'\n};\n```\nNote that the main page of SaltGUI is then located at `/app/`. When you want `/app` to work as well, you should instruct an intermediate proxy server to translate `/app` into `/app/`.\n\n\u003e Currently you can't use totally independent salt-api without proxy as support for CORS preflight request is not properly support.\n\n\n## Development environment with Docker\nTo make life a bit easier for testing SaltGUI or setting up a local development environment you can use the provided docker-compose setup in this repository to run a saltmaster with three minions, including SaltGUI:\n```\ncd docker\ndocker-compose up\n```\nThen browse to [http://localhost:3333/](http://localhost:3333/), you can login with `salt:salt`.\n\n\n## Testing\nWe provide some functional tests and unit tests. They use the docker setup to run the functional tests. You will also need [yarn](https://yarnpkg.com) and [node.js](https://nodejs.org/en/) to run them. When you have docker, yarn and node.js installed, you can run the tests from the root of the repository like this:\n```\nbash runtests.bash\n```\n\nTo show the browser window + a debugger while running the functional tests you can run:\n```\nNIGHTMARE_DEBUG=1 bash runtests.bash\n```\n\nWe use the following testing libraries:\n- [nightmare.js](https://github.com/segmentio/nightmare), for functional/browser tests\n- [mocha](https://mochajs.org/), a well documented testing framework for javascript\n- [chai](http://www.chaijs.com/), the preferred assertion library for testing\n\nYou'll need at least:\n- `docker-compose` 1.12 or above\n- `nodejs` 8.11 or above\n- `yarn` 1.7 or above\n\n\n## Known issues\nAt least in Chrome 96 and Edge 96, the \"pause\" icon is shown in its \"emoji\" form and appears in its coloured form. This also happens for the looking-glass icon in the search field.\n\n\n## Contributing\nOpen a PR! Try to use no dependencies where possible, as vanilla JS is the aim. Any libraries will need to be heavily considered first. Please see the section above as PRs won't be reviewed if they don't pass the tests.\n\n\n## Credits\nThis excellent frontend is originally written by [Oliver Dunk](https://github.com/oliverdunk).\u003cbr\u003e\nIt was then further developed by [Martijn Jacobs](https://github.com/maerteijn).\u003cbr\u003e\nIt is currently maintained by [Erwin Dondorp](https://github.com/erwindon).\n\nSaltGUI includes these libraries (with possible modifications):\n* [sorttable](https://www.kryogenix.org/code/browser/sorttable/)\n* [search-highlight](https://www.the-art-of-web.com/javascript/search-highlight/)\n* [jsonpath](https://www.w3resource.com/JSON/JSONPath-with-JavaScript.php)\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferwindon%2Fsaltgui","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ferwindon%2Fsaltgui","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ferwindon%2Fsaltgui/lists"}