{"id":35780215,"url":"https://github.com/casper-network/casper-node-launcher","last_synced_at":"2026-01-07T06:00:11.818Z","repository":{"id":37861433,"uuid":"331681317","full_name":"casper-network/casper-node-launcher","owner":"casper-network","description":"Holds the component to run and upgrade the casper-node.","archived":false,"fork":false,"pushed_at":"2025-07-24T15:19:26.000Z","size":292,"stargazers_count":9,"open_issues_count":1,"forks_count":18,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-07-24T17:06:04.595Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Rust","has_issues":true,"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/casper-network.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","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,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-01-21T16:09:25.000Z","updated_at":"2025-07-24T15:17:44.000Z","dependencies_parsed_at":"2025-02-25T17:19:00.402Z","dependency_job_id":"e546a69e-1629-4214-b560-0420ded21498","html_url":"https://github.com/casper-network/casper-node-launcher","commit_stats":null,"previous_names":[],"tags_count":16,"template":false,"template_full_name":null,"purl":"pkg:github/casper-network/casper-node-launcher","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casper-network%2Fcasper-node-launcher","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casper-network%2Fcasper-node-launcher/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casper-network%2Fcasper-node-launcher/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casper-network%2Fcasper-node-launcher/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/casper-network","download_url":"https://codeload.github.com/casper-network/casper-node-launcher/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/casper-network%2Fcasper-node-launcher/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28233227,"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":"2026-01-07T02:00:05.975Z","response_time":58,"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":[],"created_at":"2026-01-07T06:00:01.692Z","updated_at":"2026-01-07T06:00:11.681Z","avatar_url":"https://github.com/casper-network.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# casper-node-launcher\n\nA binary which runs and upgrades the casper-node of the Casper network.\n\n## Usage\n\n```\n    casper-node-launcher [OPTIONS]\n\nOPTIONS:\n    -f, --force-version \u003cversion\u003e    Forces the launcher to run the specified version of the node,\n                                     for example \"1.2.3\"\n    -h, --help                       Print help information\n    -V, --version                    Print version information\n```\n\nOn startup, launcher checks whether the installed node binaries match the installed configs,\nby comparing the version numbers.  If not, it exits with an error.\n\nThe launcher then checks if the `--force-version` parameter was provided.  If yes, it will unconditionally\nrun the specified node, given it is installed.  The requested version is then cached in the state,\nso the subsequent runs of the launcher will continue to execute the previously requested version.\n\nIf the `--force-version` parameter was not provided the launcher either tries to read its previously cached state\nfrom disk, or assumes a fresh start.  On a fresh start, the launcher searches for the highest installed\nversion of `casper-node` and starts running it in validator mode.\n\nAfter every run of the `casper-node` binary in validator mode, the launcher does the following based upon the exit code\nreturned by `casper-node`:\n  * If 0 (success), searches for the immediate next installed version of `casper-node` and runs it in migrate-data mode\n  * If 102 (downgrade), searches for the immediate previous installed version of `casper-node` and runs it in validator\n    mode\n  * If 103 (shutdown), runs the script at `/etc/casper/casper_shutdown_script` if present and exits with its exit code,\n    otherwise exits with `0`.\n  * Any other value causes the launcher to exit with an error\n\nAfter every run of the `casper-node` binary in migrate-data mode, the launcher does the following based upon the exit\ncode returned by `casper-node`:\n  * If 0 (success), runs the same version of `casper-node` in validator mode\n  * If 102 (downgrade), searches for the immediate previous installed version of `casper-node` and runs it in validator\n    mode\n  * If 103 (shutdown), runs the script at `/etc/casper/casper_shutdown_script` if present and exits with its exit code,\n    otherwise exits with `0`.\n  * Any other value causes the launcher to exit with an error\n\nIf the launcher cannot find an appropriate version at any stage of upgrading or downgrading, it exits with an error.\n\nThe default path for the casper-node's config file is `/etc/casper/1_0_0/config.toml` where the folder `1_0_0`\nindicates the semver version of the node software.\n\nThe default path for the launcher's cached state file is `/etc/casper/casper-node-launcher-state.toml`.\n\nFor testing purposes, the common folder `/etc/casper` can be overridden by setting the environment variable\n`CASPER_CONFIG_DIR` to a different folder.\n\nThe default path for the casper-node binary is `/var/lib/casper/bin/1_0_0/casper-node` where the folder `1_0_0` likewise\nindicates the version.  The default path for the casper-node-launcher binary is\n`/var/lib/casper/bin/casper-node-launcher`.\n\nFor testing purposes, the common folder `/var/lib/casper/bin` can be overridden by setting the environment variable\n`CASPER_BIN_DIR` to a different folder.\n\n## Number of Files Limit\n\nWhen `casper-node` launches, it tries to set the `nofiles` for the process to `64000`.  With some systems, this will\nhit the default hard limit of `4096`.\n\nFilehandles are used for both files and network connections.  The network connections are unpredictable and running\nout of file handles can stop critical file writes from occurring.  This limit may need to be increased from defaults.\n\nWith `casper-node-launcher` running we can see what the system allocated by finding our process id (PID) for casper-node\nwith `pgrep \"casper-node$\"`.\n\n```shell\n$ pgrep \"casper-node$\"\n275928\n```\n\nThis PID will change so you need to run the above command to get the current version with your system.  \nIt will not be `275928` each time. If you get no return, you do not have `casper-node-launcher` running properly.\n\nTo find the current `nofile` (number of open files) hard limit, we can run `prlimit` with this PID:\n\n```shell\n$ sudo prlimit -n -p 275928\nRESOURCE DESCRIPTION              SOFT HARD UNITS\nNOFILE   max number of open files 1024 4096 files\n```\n\nWe can embed both commands together so it is only `sudo prlimit -n -p $(pgrep \"casper-node$\")`.\n\n```shell\n$ sudo prlimit -n -p $(pgrep \"casper-node$\")\nRESOURCE DESCRIPTION              SOFT HARD UNITS\nNOFILE   max number of open files 1024 4096 files\n```\n\nIf you receive `prlimit: option requires an argument -- 'p'` with the above command then `pgrep \"casper-node$\"` is not\nreturning anything because `casper-node` is no longer running.\n\n### Manual increase\n\nThis is how you set `nofile` for an active process.  It will make sure you don't have issues without having to \nrestart the `casper-node-launcher` and your node's `casper-node` process.\n\nWe run `sudo prlimit --nofile=64000 --pid=$(pgrep \"casper-node$\")`.\n\nAfter this when we look at `prlimit` it should show the change:\n\n```shell\n$ sudo prlimit -n -p $(pgrep \"casper-node$\")\nRESOURCE DESCRIPTION               SOFT  HARD UNITS\nNOFILE   max number of open files 64000 64000 files\n```\n\nThis is only active while the `casper-node` process is active and therefore will not persist across server reboots, \ncasper-node-launcher restarts, and protocol upgrades.  We need to do something else to make this permanent.\n\n### limits.conf\n\nAdding the `nofile` setting for `casper` user in `/etc/security/limits.conf` will persist this value.\n\nAdd:\n\n`casper          hard    nofile          64000`\n\nto the bottom of `/etc/security/limits.conf`.\n\nAfter doing this you need to log out of any shells you have to enable this change. Restarting the node should\nmaintain the correct `nofile` setting.\n\n### systemd unit modification (bad alternative)\n\nWhen `casper-node-launcher` is installed, `/lib/systemd/system/casper-node-launcher.service` is created.  \nInside this file, a line is provided which will allow systemd to increase the `nofile` setting at launch.\n\n`#LimitNOFILE=64000`\n\nEditing this file with sudo will allow you to uncomment this line and save.  After saving you would need to run\n`sudo systemctl daemon-reload` to reload your changes.  Then you would need to restart `casper-node-launcher`.\n\nNOTE: The downside of using this method is that with upgrades to `casper-node-launcher`, the service file is replaced\nand the update would not be persistent.  Editing `/etc/security/limits.conf` is a much preferred method.\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcasper-network%2Fcasper-node-launcher","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcasper-network%2Fcasper-node-launcher","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcasper-network%2Fcasper-node-launcher/lists"}