Skip to content

Commit dd5904a

Browse files
artginzburgartginzburg
committed
feat: Up to date ReadMe
closes #22
1 parent 3bf01a4 commit dd5904a

2 files changed

Lines changed: 80 additions & 112 deletions

File tree

‎README.md‎

Lines changed: 39 additions & 112 deletions
Original file line numberDiff line numberDiff line change
@@ -17,12 +17,10 @@ Native and reliable [**TouchID**](https://support.apple.com/en-gb/guide/mac-help
1717
curl -sL git.io/sudo-touch-id | sh
1818
```
1919

20-
Now `sudo` is great, just like Safari — with your fingerprint in Terminal or whatever you're on.
20+
Now `sudo` is great, just like Safari — with your fingerprint in Terminal.
2121

2222
> <sup>Don't worry, you can also [reverse](#usage) it</sup>
2323
24-
> Note for [Ventura](https://en.wikipedia.org/wiki/MacOS_Ventura) and prior: without [full installation](#install), TouchID for `sudo` will be disabled after the next macOS *update*.
25-
2624
<div align="center">
2725

2826
<sub><sub>Result:</sub></sub>
@@ -35,160 +33,89 @@ Now `sudo` is great, just like Safari — with your fingerprint in Terminal or w
3533

3634
### Features
3735

38-
- Fast
39-
- Reliable
40-
- Written in Bash — no dependencies!
41-
- Include it to your automated system build — always working and up to date with major macOS upgrades!
36+
- Fast & reliable
37+
- Written in Bash — no dependencies
38+
- **pam_reattach support** for tmux/screen compatibility (GUI session reattachment)
39+
- **Supports modern and legacy systems:** For macOS 13 and below, see [LEGACY_MACOS.md][legacy]
4240

4341
<br />
4442

4543
## Install
4644

47-
### Via [🍺 Homebrew](https://brew.sh/) (Recommended)
45+
### Via [🍺 Homebrew](https://brew.sh/)
4846

49-
```powershell
47+
```bash
5048
brew install artginzburg/tap/sudo-touchid
51-
sudo brew services start sudo-touchid
5249
```
5350

5451
> Check out [the formula](https://github.com/artginzburg/homebrew-tap/blob/main/Formula/sudo-touchid.rb) if you're interested
5552
56-
### Using [`curl`][curl]
57-
58-
```powershell
59-
curl -sL git.io/sudo-touchid | sh
60-
```
61-
62-
<div align="right"><sup>
63-
64-
[`curl`][curl] is pre-installed in macOS
65-
66-
</sup></div>
53+
<br />
6754

68-
> Performs automated "manual" installation.
69-
<br>
55+
## Usage
7056

71-
The installation process:
72-
1. Makes the `sudo-touchid` command available.
73-
2. Makes it auto-run on every system launch <sup>(using a simple [`launchd`](https://www.launchd.info) daemon with RunAtLoad key set to true)</sup>, so that when a [macOS update erases our custom `sudo` configuration](https://www.reddit.com/r/MacOS/comments/ey2g5h/etcauto_master_keeps_getting_reset_sonce_catalina/), `sudo-touchid` fixes it again.
57+
Copy and run this command:
7458

75-
<br />
59+
```bash
60+
sudo-touchid
61+
```
7662

77-
## Usage
63+
It adds TouchID to sudo configuration, or migrates an existing legacy configuration if you're upgrading from macOS 13 or below.
7864

79-
```ps1
65+
```bash
66+
# Usage:
8067
sudo-touchid [options]
81-
# Running without options adds TouchID parameter to sudo configuration, or migrates an existing legacy configuration if you have upgraded from macOS 13 or below.
8268
[-v, --version] # Output installed version
83-
# Commands:
84-
[-d, --disable] # Removes TouchID from sudo config
85-
[--with-reattach] # Include pam_reattach.so for GUI session reattachment
86-
[--migrate] # Migrate from legacy configuration to new system
69+
[-d, --disable] # Remove TouchID from sudo config
70+
[--with-reattach] # Include pam_reattach.so for tmux/screen support
71+
[--migrate] # Migrate from legacy configuration
8772
```
8873

8974
if not installed, can be used via [`curl`][curl] <sup>bundled with macOS</sup>
9075

91-
```ps1
92-
sh <( curl -sL git.io/sudo-touch-id ) [options]
93-
# Reliability — check :)
94-
[-d, --disable] # Removes TouchID from sudo config
76+
```bash
77+
sh <( curl -sL git.io/sudo-touch-id )
9578
```
9679

80+
> Accepts the same arguments, like -d or -v.
81+
9782
<br />
9883

9984
### Why?
10085

101-
1. Productivity
102-
103-
macOS _updates_ do _reset_ `/etc/pam.d/sudo`, so previously users had to _manually_ edit the file after each upgrade.
104-
105-
> This tool was born to automate the process, allowing for TouchID sudo auth to be **quickly enabled** on a new/clean system.
106-
107-
2. Spreading the technology.
108-
109-
I bet half of you didn't know.
110-
111-
> It was there for a long time.
112-
113-
3. Lightness
114-
115-
The script is small, doesn't need any builds, doesn't need XCode.
116-
117-
##### Code size comparison — previously favoured solution VS. the one you're currently reading:
118-
119-
[![](https://img.shields.io/github/languages/code-size/mattrajca/sudo-touchid?color=brown&label=mattrajca/sudo-touchid%20—%20code%20size)](https://github.com/mattrajca/sudo-touchid)
120-
121-
![](https://img.shields.io/github/languages/code-size/artginzburg/sudo-touchid?color=teal&label=artginzburg/sudo-touchid%20—%20code%20size)
86+
- **Productivity:** Automates TouchID setup
87+
- **Lightweight:** Small Bash script, no builds or Xcode required
88+
- **Reliable:** Persistent configuration across system updates
12289

12390
<br />
12491

12592
## How does it work?
12693

127-
#### `sudo-touchid.sh` — the script:
128-
129-
**All versions:**
130-
- Automatically detects and migrates legacy configurations.
131-
- Has a `--disable` (`-d`) option that removes all TouchID configurations.
132-
- Optional `--with-reattach` for GUI session reattachment support.
133-
- Creates backup files during migration.
134-
13594
**For macOS 14+:**
136-
- Creates `/etc/pam.d/sudo_local` with TouchID configuration.
137-
- Never modifies system-managed `/etc/pam.d/sudo` file.
138-
139-
**For macOS ≤13:**
140-
- Adds `auth sufficient pam_tid.so` to the top of `/etc/pam.d/sudo` file <sup>following [@cabel's advice](https://twitter.com/cabel/status/931292107372838912)</sup>.
141-
- Creates a backup file named `sudo.bak`.
142-
- Optional `--with-reattach` flag adds `pam_reattach.so` before `pam_tid.so` for tmux/screen support.
143-
144-
<details>
145-
<summary align="right"><sub>Non-Homebrew files:</sub></summary>
146-
<br />
14795

148-
#### `com.user.sudo-touchid.plist` — the property list (global daemon):
96+
- Creates `/etc/pam.d/sudo_local` with TouchID configuration
97+
- Never modifies system-managed `/etc/pam.d/sudo` file
14998

150-
- Runs `sudo-touchid.sh` on system reload
151-
152-
> Needed because any following macOS updates just wipe out our custom `sudo`.
153-
154-
#### `install.sh` — the installer:
155-
156-
- Saves `sudo-touchid.sh` as `/usr/local/bin/sudo-touchid` and gives it the permission to execute.
157-
158-
> (yes, that also means you're able to run `sudo-touchid` from Terminal)
159-
160-
- Saves `com.user.sudo-touchid.plist` to `/Library/LaunchDaemons/` so that it's running on boot (requires root permission).
161-
</details>
99+
**All versions:**
162100

163-
<br />
101+
- Has a `--disable` (`-d`) option that removes all TouchID configurations.
102+
- Optional `--with-reattach` for GUI session reattachment support
103+
- Creates backup files during migration
104+
- Automatically detects and migrates legacy configurations
164105

165106
### Manual installation
166107

167-
1. Generally follow the steps provided by the installer in "Non-Homebrew files"
168-
2. If you need to, store `sudo-touchid.sh` anywhere else and replace `/usr/local/bin` in `com.user.sudo-touchid.plist` with the chosen path.
169-
170-
<br />
171-
172-
## Contributing
173-
174-
##### [PRs](https://github.com/artginzburg/sudo-touchid/pulls) and [Issues](https://github.com/artginzburg/sudo-touchid/issues/new/choose) are much welcome!
108+
Just save `sudo-touchid.sh` as `/usr/local/bin/sudo-touchid` with execute permissions
175109

176-
If you don't like something — change it or inform the ones willing to help.
110+
> See [LEGACY_MACOS.md][legacy] for additional considerations on older systems
177111
178112
<br />
179113

180114
## Related
181115

182-
#### Disabling password prompt for `sudo`
183-
184-
- Change `%admin ALL=(ALL) ALL` to `%admin ALL=(ALL) NOPASSWD: ALL` in `/etc/sudoers`
185-
186-
#### TouchID support in `tmux`
187-
188-
- Have a look at [pam_reattach](https://github.com/fabianishere/pam_reattach) module
189-
190-
#### Apple Watch TouchID support
191-
192-
- Have a look at [pam_watchid](https://github.com/biscuitehh/pam-watchid) module
116+
- **tmux/screen support:** [pam_reattach](https://github.com/fabianishere/pam_reattach) module (built-in via `--with-reattach`)
117+
- **Apple Watch support:** [pam_watchid](https://github.com/biscuitehh/pam-watchid) module
118+
- **Disable password prompt:** Change `%admin ALL=(ALL) ALL` to `%admin ALL=(ALL) NOPASSWD: ALL` in `/etc/sudoers`
193119

194120
[curl]: https://curl.se
121+
[legacy]: ./docs/LEGACY_MACOS.md

‎docs/LEGACY_MACOS.md‎

Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
# Legacy macOS Support (macOS 13 and below)
2+
3+
> **Note:** For macOS Ventura and prior, full installation is necessary to preserve TouchID for `sudo` through system updates.
4+
5+
## Install
6+
7+
### Via [🍺 Homebrew](https://brew.sh/) (Recommended)
8+
9+
```powershell
10+
brew install artginzburg/tap/sudo-touchid
11+
sudo brew services start sudo-touchid
12+
```
13+
14+
> Check out [the formula](https://github.com/artginzburg/homebrew-tap/blob/main/Formula/sudo-touchid.rb) if you're interested
15+
16+
### Using [`curl`][curl]
17+
18+
```bash
19+
curl -sL git.io/sudo-touchid | sh
20+
```
21+
22+
## How it works
23+
24+
- Adds `auth sufficient pam_tid.so` to the top of `/etc/pam.d/sudo` file (following [@cabel's advice](https://twitter.com/cabel/status/931292107372838912)).
25+
- Creates a backup file named `sudo.bak`.
26+
- Optional `--with-reattach` flag adds `pam_reattach.so` before `pam_tid.so` for tmux/screen support.
27+
28+
## Why?
29+
30+
macOS updates reset `/etc/pam.d/sudo`, so previously users had to manually edit the file after each upgrade. This tool automates the process by:
31+
32+
1. Making the `sudo-touchid` command available.
33+
2. Auto-running on every system launch using a simple [`launchd`](https://www.launchd.info) daemon, so that when a macOS update erases the custom `sudo` configuration, `sudo-touchid` fixes it again.
34+
35+
### Manual installation
36+
37+
1. Save `sudo-touchid.sh` as `/usr/local/bin/sudo-touchid` with execute permissions
38+
2. Save `com.user.sudo-touchid.plist` to `/Library/LaunchDaemons/` for auto-run on boot
39+
3. Customize paths in the `.plist` file if needed
40+
41+
[curl]: https://curl.se

0 commit comments

Comments
 (0)