{"id":13831973,"url":"https://github.com/aws/ec2-macos-init","last_synced_at":"2025-04-04T17:10:37.690Z","repository":{"id":38184108,"uuid":"288842558","full_name":"aws/ec2-macos-init","owner":"aws","description":"EC2 macOS Init is the launch daemon used to initialize Mac instances within EC2.","archived":false,"fork":false,"pushed_at":"2025-03-24T17:04:01.000Z","size":113,"stargazers_count":151,"open_issues_count":17,"forks_count":16,"subscribers_count":12,"default_branch":"master","last_synced_at":"2025-04-02T20:53:54.663Z","etag":null,"topics":["aws","cloud-computing","ec2","macos"],"latest_commit_sha":null,"homepage":"https://aws.amazon.com/ec2/instance-types/mac/","language":"Go","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/aws.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-08-19T21:35:17.000Z","updated_at":"2025-03-24T17:04:06.000Z","dependencies_parsed_at":"2024-10-25T17:06:28.928Z","dependency_job_id":"c3c5af8e-8f4e-470d-bda7-d9ef3d8987db","html_url":"https://github.com/aws/ec2-macos-init","commit_stats":{"total_commits":53,"total_committers":12,"mean_commits":4.416666666666667,"dds":0.7358490566037736,"last_synced_commit":"e247dee90d09488fbb5f76ce443cb01327baf44e"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Fec2-macos-init","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Fec2-macos-init/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Fec2-macos-init/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aws%2Fec2-macos-init/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aws","download_url":"https://codeload.github.com/aws/ec2-macos-init/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247217222,"owners_count":20903009,"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":["aws","cloud-computing","ec2","macos"],"created_at":"2024-08-04T10:01:46.346Z","updated_at":"2025-04-04T17:10:37.672Z","avatar_url":"https://github.com/aws.png","language":"Go","readme":"# EC2 macOS Init\n\n## Overview\n**EC2 macOS Init** is the launch daemon used to initialize Mac instances within EC2. It runs many tasks quickly and \nin parallel through the use of Priority Groups. Priority Groups are logical groupings of tasks which can be run \nat the same time without impacting each other. EC2 macOS Init will wait for all modules in a priority group to \ncomplete before moving on to the next group.\n\nImportant files for EC2 macOS Init are located in the following locations:\n\n* `/usr/local/aws/ec2-macos-init/init.toml` - The configuration file used when EC2 macOS Init is run.\n* `/usr/local/aws/ec2-macos-init/instances/\u003cinstance-id\u003e/` - The location of all instance history (previous runs).\n* `/usr/local/bin/ec2-macos-init` - The EC2 macOS Init binary file.\n* `/Library/LaunchDaemons/com.amazon.ec2.macos-init.plist` - The `launchd` plist file used to trigger EC2 macOS Init to \nrun on boot.\n\n## Usage\nMost of the time, no interaction with EC2 macOS Init will be needed. It is automatically run on every boot by `launchd` \nusing the included `com.amazon.ec2.macos-init.plist` file. However, it can also be used interactively with the \nfollowing options:\n\n### Run\n```\nsudo ec2-macos-init run\n```\n\nThe `run` flag runs EC2 macOS Init using the current configuration located at `/usr/local/aws/ec2-macos-init/init.toml`. \nIf EC2 macOS Init has been previously run on the current instance, the instance history will be read and the current \nrun will be treated as a second boot (things may be skipped depending on their run type).\n\n### Clean\n```\nsudo ec2-macos-init clean (-all)\n```\n\nThe `clean` flag removes instance history located in the `/usr/local/aws/ec2-macos-init/instances/` directory. With no \narguments, it will only remove any history matching the current instance ID. If provided `-all`, it will remove all \ninstance history. This easily allows EC2 macOS Init to be re-run as though it were the first boot, something which is \nrecommended as a part of the process to generate a custom AMI from a currently running instance resulting in a \nclean history for the new AMI.\n\n### Version\n```\nsudo ec2-macos-init version\n```\n\nThe `version` flag returns the current version of EC2 macOS init as well as the date of the commit used to build the \nexecutable.\n\n## Init.toml Configuration Options\nEC2 macOS Init uses a single [TOML](https://toml.io/) file to configure boot options. These are divided into modules \nwhich can be added to any launch group and run in any order. Current modules and options include:\n\n### Common Options\nThe following options are available for all modules:\n\n* `Name` (`string`) - Required; This is a unique string used to identify the module both in logging and instance history.\n* `PriorityGroup` (`int`) - Required; An integer defining the priority group. Modules with the same Priority Group \nnumber will run in parallel. \n* `FatalOnError` (`bool`) - Optional; Fatal on error will halt the run at the current group and not continue to later \nPriority Groups. Defaults to `false`.\n\nAdditionally, all module configurations must contain exactly one of the following, set to `true`:\n\n* `RunOnce` (`bool`) - Required; Run this module only once, ever. Any history of a module with this set will prevent it \nfrom running again. Defaults to `false`.\n* `RunPerBoot` (`bool`) - Required; Run this module on every boot. Defaults to `false`.\n* `RunPerInstance` (`bool`) - Required; Run this module once per instance ID. Defaults to `false`.\n\n### Command\nThe `Command` module runs a single command. This can be used for a wide variety of tasks on launch. It should be noted \nthat any shell redirection will not work as anticipated as this is intended only for simple commands. In more complex \ncases, it's suggested to use this module to execute a shell script containing the required commands.\n\n* `Cmd` (`string array`) - Required; This is the command to be run. The first element should be the name of the \nexecutable and all following elements are arguments.\n* `RunAsUser` (`string`) - Optional; The user the command should be run as. Default is `root`.\n* `EnvironmentVars` (`[]string`) - Optional; A slice of environment variables in the form `key=value`. Default is \nempty.\n\t\n#### Example\n```toml\n[[Module]]\n  Name = \"Important-Init-Command\"\n  PriorityGroup = 4 # Fourth group\n  RunOnce = true # Run once, ever\n  FatalOnError = true # Stop running Init if there is an error \n  [Module.Command]\n    Cmd = [\"touch\", \"/tmp/file.txt\"] # A simple command\n    RunAsUser = \"ec2-user\" # Run as ec2-user\n    EnvironmentVars = [\"MY_KEY=myValue\"] # One environment variable named MY_KEY\n```\n\n### Network Check\nThe `NetworkCheck` module gets the default gateway and pings it to check if the network is up. This is useful as a \nway to gate subsequent modules which require network access (internet or IMDS).\n\n* `PingCount` (`int`) - Optional; The number of ping attempts to try against the default gateway. Default is `3`.\n\n#### Example\n```toml\n[[Module]]\n  Name = \"Network-Check\"\n  PriorityGroup = 1 # First group\n  RunPerBoot = true # Run every boot\n  FatalOnError = true # Fatal if there's an error - this must succeed\n  [Module.NetworkCheck]\n    PingCount = 6 # Six attempts\n```\n\n### SSH Keys\nThe `SSHKeys` module manages the `.ssh/authorized_keys` file on boot.  There are many options here, but it is primarily \nused to pull OpenSSH keys from IMDS on first launch.\n\n* `DedupKeys` (`bool`) - Optional; Enable deduplication of keys. This option will cause the entire `authorized_keys` \nfile for the user (default is `ec2-user`) to be read and all keys will be deduplicated. This is useful in preventing \nthe user's keys file from having many of the same key after multiple launches. Default is `false`.\n* `GetIMDSOpenSSHKey` (`bool`) - Optional; Get the OpenSSH key from IMDS, if provided. On launch of an EC2 instance, \nusers are offered the option to provide an EC2 Key Pair. This option will add that OpenSSH key to `authorized_keys`. \nDefault is `false`.\n* `StaticOpenSSHKeys` (`[]string`) - Optional; This option takes a string array of keys in SSH RSA public key \nformat (`ssh-rsa \u003cmaterial\u003e \u003ccomment\u003e`) and adds them to `authorized_keys`. Default is empty.\n* `OverwriteAuthorizedKeys` (`bool`) - Optional; Overwrite the `authorized_keys` file each time this module runs. \nThis can be useful in ensuring that old keys are removed every launch and replaced by new ones through either of the \nIMDS or static key options. Default is `false`.\n* `User` (`string`) - Optional; The owner of the `authorized_keys` file. Default is `ec2-user`.\n\n#### Example\n```toml\n[[Module]]\n  Name = \"Get-SSH-Keys\"\n  PriorityGroup = 3 # Third group\n  FatalOnError = true # Exit on failure - this is required to log in\n  RunPerInstance = true # Run only once per instance\n  [Module.SSHKeys]\n    GetIMDSOpenSSHKey = true # Get the key from IMDS\n    User = \"ec2-user\" # Apply the key to ec2-user\n    DedupKeys = true # Remove duplicate keys\n    OverwriteAuthorizedKeys = false # Append to authorized_keys to avoid erasing any additional keys on future instances\n```\n\n### Userdata\nThe `UserData` module pulls User Data from IMDS and provides the option to execute it. This is stored in a file at \n`/usr/local/aws/ec2-macos-init/instances/\u003cinstance-id\u003e/userdata`. This can be useful for non-executables (like JSON) \n as well, by pulling the data from IMDS and making it immediately available without having to retrieve it directly.\n\n* `ExecuteUserData` (`bool`) - Optional; If set to `true`, Init will treat the userdata file as an executable and \nattempt to run it. Default is `false`.\n\n#### Example\n```toml\n[[Module]]\n  Name = \"Execute-User-Data\"\n  PriorityGroup = 4 # Fourth group\n  RunPerInstance = true # Run once per instance\n  FatalOnError = false # Best effort, don't fatal on error\n  [Module.UserData]\n    ExecuteUserData = true # Execute the userdata\n```\n\n### System Configuration\nThe `SystemConfig` module provides a few interfaces for setting system configuration parameters, primarily through \nthe use of `sysctl` and `defaults`.\n\n* `[Module.SystemConfig.Sysctl]` - Optional; Contains the value to be set by `sysctl`.\n    * `value` (`string`) - Required; The value in the form: `\"parameter=value\"`.\n* `[Module.SystemConfig.Defaults]` - Optional; Contains a parameter and value to be set by `defaults`.\n    * `plist` (`string`) - Required; The plist to containing the parameter to be set.\n    * `parameter` (`string`) - Required; The parameter to be updated.\n    * `type` (`string`) - Required; The type of parameter to be set. Currently, this can only be `\"bool\"`.\n    * `value` (`string`) - Required; The value to assign to the plist parameter.\n* `secureSSHDConfig` (`bool`) - Optional; Reapply the default SSHD config security settings after an OS update.\n\n#### Example\n```toml\n[[Module]]\n  Name = \"System-Configuration\"\n  PriorityGroup = 2 # Second group\n  RunPerBoot = true # Run every boot to enforce these parameters\n  FatalOnError = false # Best effort, don't fatal on error\n  [Module.SystemConfig]\n    secureSSHDConfig = true # secure sshd_config on OS update\n    [[Module.SystemConfig.Sysctl]]\n      value = \"my.favorite.parameter=42\" # use sysctl to set my.favorite.parameter\n    [[Module.SystemConfig.Defaults]]\n      plist = \"/Library/Preferences/com.amazon.ec2.plist\" # use defaults to set a parameter in this plist\n      parameter = \"PlistParameter\"\n      type = \"bool\"\n      value = \"false\"\n```\n\n\n### User Management\nThe `UserManagement` module provides the ability to safely randomize an existing user's password. \n\n* `User` (`string`) - Optional; The user (which must already exist) to manage. Default is `ec2-user`.\n* `RandomizePassword` (`bool`) - Optional; Configures whether the user's password should be randomized \n  on first boot. Default is `true`.\n  \n#### Example\n```toml\n[[Module]]\n  Name = \"ManageEC2User\"\n  PriorityGroup = 2 # Second group\n  RunOnce = true # Run only on the first boot\n  FatalOnError = true # Must succeed\n  [Module.UserManagement]\n    User = \"ec2-user\" # This user must exist locally in /Users/\n    RandomizePassword = true # default is true\n```\n\n## Building\n\nThe `build.sh` script has been provided for easy builds.  This script sets build-time variables, gets dependencies, \nand then builds the binary for `darwin/amd64`.  Once complete, the binary, launchd plist, and `init.toml` configuration \nfile need to be copied to the locations described in the Overview section of this README before testing.\n\n## Contributing\n\nPlease feel free to submit issues, fork the repository and send pull requests! \nSee [CONTRIBUTING](CONTRIBUTING.md) for more information.\n\n## Security\n\nSee the Security section of [CONTRIBUTING](CONTRIBUTING.md#security-issue-notifications) for more information.\n\n## License\n\nThis project is licensed under the Apache-2.0 License.","funding_links":[],"categories":["Go"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Fec2-macos-init","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faws%2Fec2-macos-init","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faws%2Fec2-macos-init/lists"}