# cosu - Conditional su

**cosu** (conditional su) intelligently determines whether to run a command with `sudo` based on file permission checks. Instead of blindly running commands with elevated privileges, cosu only escalates when necessary.

## Installation

```bash
make install
```

To install to a custom location:

```bash
make PREFIX=/opt/local install
```

To uninstall:

```bash
make uninstall
```

## Usage

```bash
cosu [FLAGS PATH]... -- COMMAND [ARGS...]
```

### Flags

- `-r, --read`: Check read permission on the following path
- `-w, --write`: Check write permission on the following path
- `-x, --execute`: Check execute permission on the following path
- `-h, --help`: Display help message

Multiple flags can be specified before a single path to check multiple permissions. Short flags can be combined in a single argument (e.g., `-rw` is equivalent to `-r -w`).

## How It Works

1. cosu checks if the current user has the specified permissions on the given paths
2. If **any** permission check fails, the command is executed with `sudo`
3. If **all** permission checks pass, the command runs without privilege escalation

## Examples

### Docker

Check if the user can access the Docker socket before running Docker commands:

```bash
cosu -rw /var/run/docker.sock -- docker ps
cosu -rw /var/run/docker.sock -- docker images
cosu -rw /var/run/docker.sock -- docker run -it alpine sh
```

Check Docker data directory access:

```bash
cosu -r /var/lib/docker -- docker system df
```

### Incus (LXD)

Check Unix socket permissions for Incus:

```bash
cosu -rw /var/lib/incus/unix.socket -- incus list
cosu -rw /var/lib/incus/unix.socket -- incus launch ubuntu:22.04 mycontainer
cosu -rw /var/lib/incus/unix.socket -- incus exec mycontainer -- bash
```

Check Incus directory access:

```bash
cosu -r /var/lib/incus -- incus storage list
```

### General System Administration

Edit system configuration files:

```bash
cosu -w /etc/nginx/nginx.conf -- vim /etc/nginx/nginx.conf
cosu -rw /etc/hosts -- nano /etc/hosts
```

Execute privileged binaries:

```bash
cosu -x /usr/sbin/iptables -- iptables -L
cosu -x /sbin/reboot -- reboot
```

Multiple path checks:

```bash
cosu -r /etc/ssl/private -w /var/log/app.log -- /opt/myapp/run
```

Check multiple permissions on a single path:

```bash
cosu -rwx /opt/app/data -- /opt/app/run
```

## Why Use cosu?

### Traditional Approach Problems

```bash
sudo docker ps          # Always runs as root
alias docker='sudo docker'  # Permanently elevated, security risk
```

### Benefits of cosu

- **Least Privilege**: Only escalates when necessary
- **No Configuration**: No need to modify sudoers or add users to groups
- **Transparent**: Works with existing commands
- **Safe**: Checks permissions before execution

## Creating Aliases

You can create convenient aliases in your shell:

```bash
alias docker='cosu -rw /var/run/docker.sock -- docker'
alias incus='cosu -rw /var/lib/incus/unix.socket -- incus'
```

Now these commands automatically escalate only when needed:

```bash
docker ps        # Runs with sudo only if socket is inaccessible
incus list       # Runs with sudo only if socket is inaccessible
```

## Advanced Usage

### Multiple Paths

Check multiple independent paths:

```bash
cosu -r /etc/app/config.ini -w /var/log/app.log -x /opt/app/bin -- /opt/app/bin/run
```

### Complex Permission Requirements

Check if a path is both readable and writable:

```bash
cosu -rw /var/lib/database -- psql -U postgres
```

## Exit Status

cosu returns the exit status of the executed command, whether run with or without sudo.

## Requirements

- Bash 4.0 or later
- `sudo` (when privilege escalation is needed)

## License

MIT License - see LICENSE file for details

## See Also

- `sudo(8)` - execute a command as another user
- `test(1)` - check file types and compare values
- Man page: `man cosu`