{"id":13581621,"url":"https://github.com/coreos/locksmith","last_synced_at":"2025-04-06T10:32:40.866Z","repository":{"id":16538196,"uuid":"19291599","full_name":"coreos/locksmith","owner":"coreos","description":"Reboot manager for Container Linux","archived":true,"fork":false,"pushed_at":"2018-07-30T08:48:19.000Z","size":669,"stargazers_count":274,"open_issues_count":9,"forks_count":63,"subscribers_count":23,"default_branch":"master","last_synced_at":"2024-11-05T21:44:51.332Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":false,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/coreos.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"code-of-conduct.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2014-04-29T21:10:19.000Z","updated_at":"2024-02-26T20:36:10.000Z","dependencies_parsed_at":"2022-07-30T19:08:02.970Z","dependency_job_id":null,"html_url":"https://github.com/coreos/locksmith","commit_stats":null,"previous_names":[],"tags_count":26,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coreos%2Flocksmith","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coreos%2Flocksmith/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coreos%2Flocksmith/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/coreos%2Flocksmith/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/coreos","download_url":"https://codeload.github.com/coreos/locksmith/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247470375,"owners_count":20944146,"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":[],"created_at":"2024-08-01T15:02:08.222Z","updated_at":"2025-04-06T10:32:39.546Z","avatar_url":"https://github.com/coreos.png","language":"Go","funding_links":[],"categories":["Go"],"sub_categories":[],"readme":"# locksmith\n\nlocksmith is a reboot manager for the CoreOS update engine which is able to use\netcd to ensure that only a subset of a cluster of machines are rebooting\nat any given time. `locksmithd` runs as a daemon on CoreOS machines and is\nresponsible for controlling the reboot behaviour after updates.\n\n## Configuration\n\nThere are three different strategies that `locksmithd` can use after the update\nengine has successfully applied an update:\n\n- `etcd-lock` - reboot after first taking a lock in etcd.\n- `reboot` - reboot without taking a lock.\n- `off` - causes locksmithd to exit and do nothing.\n\nThese strategies will either be followed immediately after an update, or during\nthe next available [reboot window](#reboot-windows) if one has been configured.\n\nThese strategies can be configured via `/etc/coreos/update.conf` with a line that looks like:\n\n```\nREBOOT_STRATEGY=reboot\n```\n\nThe reboot strategy can also be configured through a [Container Linux Config](https://github.com/coreos/container-linux-config-transpiler/blob/master/doc/getting-started.md).\n\nThe default strategy is to follow the `etcd-lock` strategy if etcd is running,\nand to otherwise follow the `reboot` strategy.\n\n## Usage\n\n`locksmithctl` is a simple client that can be use to introspect and control the\nlock used by locksmith.  It is installed by default on CoreOS.\n\nRun `locksmithctl -help` for a list of command-line options.\n\nAll command-line options can also be specified using environment variables with\na `LOCKSMITHCTL_` prefix. For example, the `-endpoint` argument can be set\nusing `LOCKSMITHCTL_ENDPOINT`.\n\n### Connecting to multiple endpoints\n\nMultiple endpoints can be specified by passing the `-endpoint=\u003curl\u003e` option for\neach endpoint, or by passing a comma-separated list of endpoints, e.g.:\n\n    -endpoint=\u003curl\u003e,\u003curl\u003e\n\nSpecifying multiple endpoints using an environment variable is supported by\npassing a comma-delimited list, e.g.:\n\n    LOCKSMITHCTL_ENDPOINT=\u003curl\u003e,\u003curl\u003e\n\n### Listing the Holders\n\n```\n$ locksmithctl status\nAvailable: 0\nMax: 1\n\nMACHINE ID\n69d27b356a94476da859461d3a3bc6fd\n```\n\n### Unlock Holders\n\nIn some cases a machine may go away permanently or semi-permanently while\nholding a reboot lock. A system administrator can clear the lock of a specific\nmachine using the unlock command:\n\n```\n$ locksmithctl unlock 69d27b356a94476da859461d3a3bc6fd\n```\n\n### Maximum Semaphore\n\nBy default the reboot lock only allows a single holder. However, a user may\nwant more than a single machine to be upgrading at a time. This can be done by\nincreasing the semaphore count.\n\n```\n$ locksmithctl set-max 4\nOld: 1\nNew: 4\n```\n\n## Groups\n\n`locksmithd` coordinates the reboot lock in groups of machines. The default\ngroup is \"\", or the empty string. `locksmithd` will only coordinate the reboot\nlock with other machines in the same group.\n\nThe purpose of groups is to allow faster updating of certain sets of machines\nwhile maintaining availability of certain services. For example, in a cluster\nof 5 CoreOS machines with all machines in the default group, if you have 2 load\nbalancers and run `locksmithctl set-max 2`, then it is possible that both load\nbalancers would be rebooted at the same time, interrupting the service they\nprovide. However, if the load balancers are put into their own group named \"lb\",\nand both the default group and the \"lb\" group have a max holder of 1, two\nreboots can occur at once, but both load balancers will never reboot at the same\ntime.\n\n### Configuring groups\n\nTo place machines in a group other than the default, `locksmithd` must be started\nwith the `-group=groupname` flag or set the `LOCKSMITHD_GROUP=groupname` environment\nvariable.\n\nTo control the semaphore of a group other than the default, you must invoke\n`locksmithctl` with the `-group=groupname` flag or set the `LOCKSMITHCTL_GROUP=groupname`\nenvironment variable.\n\n## Reboot windows\n\n`locksmithd` can be configured to only reboot during certain timeframes. These\nreboot windows work with any reboot strategy.\n\nThe reboot window is configured through two environment variables,\n`LOCKSMITHD_REBOOT_WINDOW_START` and `LOCKSMITHD_REBOOT_WINDOW_LENGTH`. Note that\n`REBOOT_WINDOW_START` and `REBOOT_WINDOW_LENGTH` are also acceptable. Here is\nan example configuration:\n\n```\nLOCKSMITHD_REBOOT_WINDOW_START=14:00\nLOCKSMITHD_REBOOT_WINDOW_LENGTH=1h\n```\n\nThis would configure `locksmithd` to only reboot between 2pm and 3pm. Optionally,\na day of week may be specified for the start of the window:\n\n```\nLOCKSMITHD_REBOOT_WINDOW_START=\"Thu 23:00\"\nLOCKSMITHD_REBOOT_WINDOW_LENGTH=1h30m\n```\n\nThis would configure `locksmithd` to only reboot the system on Thursday after 11pm,\nor on Friday before 12:30am.\n\nCurrently, the only supported values for the day of week are short day names,\ne.g. `Sun`, `Mon`, `Tue`, `Wed`, `Thu`, `Fri`, and `Sat`, but the day of week can\nbe upper or lower case. The time of day must be specified in 24-hour time format.\nThe window length is expressed as input to go's [time.ParseDuration][time.ParseDuration]\nfunction.\n\n[time.ParseDuration]: http://godoc.org/time#ParseDuration\n\n## Implementation details\n\nThe following section describes how locksmith works under the hood.\n\n### Semaphore\n\nlocksmith uses a [semaphore][semaphore] in etcd, located at the key\n`coreos.com/updateengine/rebootlock/semaphore`, to coordinate the reboot lock.\nIf a non-default group name is used, the etcd key will be\n`coreos.com/updateengine/rebootlock/groups/$groupname/semaphore`.\n\nThe semaphore is a JSON document, describing a simple semaphore, that clients [swap][cas]\nto take the lock.\n\nWhen it is first created it will be initialized like so:\n\n```json\n{\n\t\"semaphore\": 1,\n\t\"max\": 1,\n\t\"holders\": []\n}\n```\n\nFor a client to take the lock, the document is swapped with this:\n\n```json\n{\n\t\"semaphore\": 0,\n\t\"max\": 1,\n\t\"holders\": [\n\t\t\"69d27b356a94476da859461d3a3bc6fd\"\n\t]\n}\n```\n\n## Bugs\n\nPlease use the [CoreOS issue tracker][bugs] to report all bugs, issues, and feature requests.\n\n[semaphore]: http://en.wikipedia.org/wiki/Semaphore_(programming)\n[cas]: https://coreos.com/etcd/docs/latest/api.html#atomic-compare-and-swap\n[bugs]: https://github.com/coreos/bugs/issues/new?labels=component/locksmith\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoreos%2Flocksmith","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcoreos%2Flocksmith","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcoreos%2Flocksmith/lists"}