Skip to content

Commit

Permalink
Update Documentation
Browse files Browse the repository at this point in the history
  • Loading branch information
newtoallofthis123 committed Aug 29, 2024
1 parent 0e96057 commit 9858cef
Show file tree
Hide file tree
Showing 6 changed files with 17 additions and 33 deletions.
3 changes: 1 addition & 2 deletions INSTALL.md
Original file line number Diff line number Diff line change
Expand Up @@ -10,7 +10,6 @@ We have packaged `swhkd-git`. `swhkd-bin` has been packaged separately by a user

**Runtime:**

- Policy Kit Daemon ( polkit )
- Uinput kernel module
- Evdev kernel module

Expand All @@ -34,5 +33,5 @@ We have packaged `swhkd-git`. `swhkd-bin` has been packaged separately by a user

```
swhks &
pkexec swhkd
swhkd
```
20 changes: 9 additions & 11 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,7 @@ Xorg or Wayland desktops, and you can even use `swhkd` in a TTY.

```bash
swhks &
pkexec swhkd
swhkd
```

## Runtime signals
Expand All @@ -50,9 +50,7 @@ After opening `swhkd`, you can control the program through signals:
`swhkd` closely follows `sxhkd` syntax, so most existing `sxhkd` configs should
be functional with `swhkd`.

The default configuration file is in `/etc/swhkd/swhkdrc`. If you don't like
having to edit the file as root every single time, you can create a symlink from
`~/.config/swhkd/swhkdrc` to `/etc/swhkd/swhkdrc`.
The default configuration file is in `~/.config/swhkd/swhkdrc` with a fallback to `etc/swhkd/swhkdrc`.

If you use Vim, you can get `swhkd` config syntax highlighting with the
[swhkd-vim](https://github.com/waycrate/swhkd-vim) plugin. Install it in
Expand All @@ -75,13 +73,13 @@ All supported key and modifier names are listed in `man 5 swhkd-keys`.
## Security

We use a server-client model to keep you safe. The daemon (`swhkd` — privileged
process) communicates to the server (`swhks` — running as non-root user) after
checking for valid keybindings. Since the daemon is totally separate from the
server, no other process can read your keystrokes. As for shell commands, you
might be thinking that any program can send shell commands to the server and
that's true! But the server runs the commands as the currently logged-in user,
so no extra permissions are provided (This is essentially the same as any app on
your desktop calling shell commands).
process) is responsible for listening to key events and running shell commands.
The server (`swhks` — non-privileged process) is responsible for keeping a track of the
environment variables and sending them to the daemon. The daemon
uses these environment variables while running the shell commands.
The daemon only runs shell commands that have been parsed from the config file and there is no way to
run arbitrary shell commands. The server is responsible for only sending the environment variables to the daemon and nothing else.
This seperation of responsibilities ensures security.

So yes, you're safe!

Expand Down
14 changes: 5 additions & 9 deletions docs/swhkd.1.scd
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,11 @@ swhkd - Hotkey daemon inspired by sxhkd written in Rust

# SYNOPSIS

*pkexec swhkd* [_flags_]
*swhkd* [_flags_]

# CONFIG FILE

The config file goes in */etc/swhkd/swhkdrc*. Since swhkd is written with a pkexec privilege escalation model in mind, we can't detect
*$XDG_CONFIG_HOME*.

This can be avoided as such:
- Using the *include* statement in your config file.
- Using the *-c* flag to mention a custom config file at runtime.
- Symlinking the config file from *~/.config/swhkd/swhkdrc* or any other directory of choice to */etc/swhkd/swhkdrc*.

The config file goes in *~/.config/swhkd/swhkdrc* with a fallback to */etc/swhkd/swhkdrc*.
More about the config file syntax in `swhkd(5)`

# OPTIONS
Expand All @@ -41,6 +34,9 @@ More about the config file syntax in `swhkd(5)`
*-D, --device* <DEVICE_NAME>
Manually set the keyboard devices to use. Can occur multiple times.

*-r, --refresh* <REFRESH_TIME>
Manually set the refresh time to check the server for a new environment

# SIGNALS

- Reload config file: `sudo pkill -HUP swhkd`
Expand Down
3 changes: 2 additions & 1 deletion docs/swhkd.5.scd
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,8 @@ swhkd - Hotkey daemon inspired by sxhkd written in Rust

# CONFIG FILE

- A global config can be defined in */etc/swhkd/swhkdrc*. Swhkd attempts to look in your *$XDG_CONFIG_HOME*, failing which it defaults to *~/.config*.
- A global config can be defined in *~/.config/swhkd/swhkdrc*, with a
fallback to */etc/swhkd/swhkdrc*. Swhkd attempts to look in your *$XDG_CONFIG_HOME*, failing which it defaults to *~/.config*.
- A local config overrides the global one. Local configs should be placed in the root of the project.

# SYNTAX
Expand Down
6 changes: 0 additions & 6 deletions docs/swhks.1.scd
Original file line number Diff line number Diff line change
Expand Up @@ -16,12 +16,6 @@ swhks - Server for swhkd, used to run user level commands over IPC.
*-V*, *--version*
Print version information.

*-l*, *--log* <LOG_FILE_PATH>
Set a log file path.
If *XDG_DATA_HOME* exists then we use *swhks/swhks-current_time.log* relative to
it, else we use *.local/share/swhks/swhks-current_time.log* relative to the
user home directory.

*-d*, *--debug*
Enable debug mode.

Expand Down
4 changes: 0 additions & 4 deletions swhks/src/main.rs
Original file line number Diff line number Diff line change
Expand Up @@ -23,10 +23,6 @@ use sysinfo::{ProcessExt, SystemExt};
#[derive(Parser)]
#[command(version, about, long_about = None)]
struct Args {
/// Set a custom log file. (Defaults to ${XDG_DATA_HOME:-$HOME/.local/share}/swhks-current_unix_time.log)
#[arg(short, long, value_name = "FILE")]
log: Option<PathBuf>,

/// Enable Debug Mode
#[arg(short, long)]
debug: bool,
Expand Down

0 comments on commit 9858cef

Please sign in to comment.