{"id":14063713,"url":"https://github.com/serverscom/ResourceLocker","last_synced_at":"2025-07-29T16:31:21.512Z","repository":{"id":131002397,"uuid":"161235773","full_name":"serverscom/ResourceLocker","owner":"serverscom","description":"A network host synchronization framework that helps to prevent unexpected downtime during maintenance.","archived":false,"fork":false,"pushed_at":"2019-03-23T18:32:00.000Z","size":24,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-12-04T01:35:02.375Z","etag":null,"topics":["powershell","powershell-module","synchronization"],"latest_commit_sha":null,"homepage":"https://www.powershellgallery.com/packages/ResourceLocker/","language":"PowerShell","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/serverscom.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,"roadmap":null,"authors":null,"dei":null}},"created_at":"2018-12-10T21:00:56.000Z","updated_at":"2024-06-05T12:31:03.000Z","dependencies_parsed_at":"2023-05-24T21:30:20.116Z","dependency_job_id":null,"html_url":"https://github.com/serverscom/ResourceLocker","commit_stats":null,"previous_names":["serverscom/resourcelocker"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/serverscom/ResourceLocker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serverscom%2FResourceLocker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serverscom%2FResourceLocker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serverscom%2FResourceLocker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serverscom%2FResourceLocker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/serverscom","download_url":"https://codeload.github.com/serverscom/ResourceLocker/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/serverscom%2FResourceLocker/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267718272,"owners_count":24133448,"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","status":"online","status_checked_at":"2025-07-29T02:00:12.549Z","response_time":2574,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":["powershell","powershell-module","synchronization"],"created_at":"2024-08-13T07:03:28.321Z","updated_at":"2025-07-29T16:31:20.884Z","avatar_url":"https://github.com/serverscom.png","language":"PowerShell","funding_links":[],"categories":["PowerShell"],"sub_categories":[],"readme":"# ResourceLocker\nThe purpose of the module is to synchronize different functions/scripts which make one or more network hosts unavailable as a part of their process. It is achieved by introducing \"locks\" which each function or a script can put on a network host, therefore stating that that function is currently working with that host, which, in turn, is a signal to other functions that they better not make that host unavailable.\nA good example would be a maintenance module, like AutomaticMaintenance, which reboots servers as it performs maintenance on them. We'd like to prevent it from rebooting a host which is currently in use by, say, an OS image release function.\n\n## Locking\n\nTo *lock* a resource (a network host or file), use one of the following functions:\n* `Lock-HostResource` - to put a lock on a network host. You can choose the type of a lock: `Generic` or `Host` (see below).\n* `Lock-FileResource` - to put a lock on a fileserver where some file, with which you'd like to work, resides. No need to provide server's name separately - just pass a link to the file and let the function to do its job. Results in a lock of the `File` type.\n* `Lock-Resource` - the other two functions use this one to actually put a lock in place. It provides additional advanced parameters which aren't really needed for day-to-day operations.\n\n### Lock types\nCurrently there are three types of locks:\n* **Host** - Only one lock of this type is allowed per host. Use it to lock a host exclusively - it will render any subsequent lock commands against the host to fail. Useful when you prepare a host for reboot.\n* **Generic** - Multiple locks of this type per host allowed. Just shows that something works with the host right now.\n* **File** - Behaves like a Generic lock, but is useful for network file operations, since it might contain the full path of a network file in the description.\n\n### Under the hood\nA lock is just a file with the `.lock` extension. By default lock files are located in a shared folder called `ResourceLocks` on a locked host.\nThere are several sections in a lock file:\n* **Caller** - Arbitrary description of an entity which set the lock. We recommend to pass the name of a caller function here.\n* **Description** - Arbitrary description why the host was locked. **Lock-FileResource** fills this section with a path to the file.\n* **LockedAt** - Time, when the lock was set, in ticks.\n* **UnlockedAt** - Time, when the lock was removed, in ticks.\n\nWhen you create a lock, a unique session ID is generated. This ID then used for *all* locks in the dependency tree, which makes troubleshooting easier.\n\n### Unlocking\nTo *unlock* a resource, use `Unlock-Resource` function. You must pass a lock object to it, which it will process and, as the result of this, the lock will be moved into *the archive* and a new section of the lock file, UnlockedAt, will be filled with the current time in ticks.\nRight now, the archive is a folder inside the `ResourceLocks` folder called `History`.\n\n## Host dependencies\nThe module supports a dependencies map, which defines dependencies between network hosts. In a `ResourceLocker-Dependencies.json` file you can define for each host, which hosts depend on it. Then, when you lock the dependent, hosts, on which it depends, will be automatically locked as well.\n\nYou can see the full dependency tree for a host by using the **Get-ResourceDependence** function.\n\n```yaml\n{\n    \"hv01\": [\n        \"dc01\",\n        \"vmm01\"\n    ]\n}\n```\nIn this example, two hosts depend on HV01: DC01 and VMM01 - if any of them gets locked, HV01 will be locked too.\n\n```powershell\nGet-ResourceDependence -ResourceName dc01\nhv01\n\nGet-ResourceDependence -ResourceName vmm01\nhv01\n```\n\n```yaml\n{\n    \"hv01\": [\n        \"dc01\",\n        \"vmm01\"\n    ]\n    \"dc01\": [\n        \"dc02\"\n    ],\n    \"dc02\": [\n        \"dc01\"\n    ]\n}\n```\nIn this example we added a cross-dependency between DC01/DC02, which means if one of them gets locked, the other one becomes locked too - you don't want all your domain controllers to be down at once and such configuration helps to prevent just that.\n\n```powershell\nGet-ResourceDependence -ResourceName dc01\ndc02\nhv01\n\nGet-ResourceDependence -ResourceName dc02\ndc01\nhv01\n```\n\n## Exported functions\n* [Get-ResourceDependence](docs/Get-ResourceDependence.md)\n* [Get-ResourceLockId](docs/Get-ResourceLockId.md)\n* [Lock-FileResource](docs/Lock-FileResource.md)\n* [Lock-HostResource](docs/Lock-HostResource.md)\n* [Lock-Resource](docs/Lock-Resource.md)\n* [Test-HostResourceLock](docs/Test-HostResourceLock.md)\n* [Unlock-Resource](docs/Unlock-Resource.md)\n\n## Module-wide variables\nThere are several variables defined in the .psm1-file, which are used by the module's functions as default values for parameters:\n\n`[string]$ModuleWideResourceDependenciesFilePath` - default value for **Get-ResourceDependence**'s `-FilePath` parameter.\n\n`[int]$ModuleWideLockTimeout` - default value for **Lock-Resource**'s `-Timeout` parameter.\n\n`[int]$ModuleWideLockRetries` - default value for **Lock-Resource**'s `-Retry` parameter.\n\n`[string]$ModuleWideLockHistoryFolderName` - default value for **Unlock-Resource**'s `-HistoryFolderName` parameter.\n\n`[string]$ModuleWideLockFileNameTemplate` - default value for the `-FileNameTemplate` parameter of **New-ResourceLock**, **Test-HostResourceLock**, and **Unlock-Resource** functions.\n\n`[string]$ModuleWideLockFolderPathTemplate` - default value for the `-FolderPathTemplate` parameter of **New-ResourceLock** and **Test-HostResourceLock** functions.\n\n## Loading variables from an external source\nAll module-wide variables can be redefined with a `Config.ps1` file, located in the module's root folder. Just put variable definitions in there as you would do with any other PowerShell script. You may find an example of a config file `Config-Example.ps1` in the module's root folder.\n\n## Limitations\n* The module requires network hosts to be available through the SMB protocol.\n* The module supports implicit authentication only.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserverscom%2FResourceLocker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fserverscom%2FResourceLocker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fserverscom%2FResourceLocker/lists"}