gitea-mirror/rosenpass
1
0
Fork 0
mirror of https://github.com/rosenpass/rosenpass.git synced 2025-12-05 20:40:02 -08:00
Code Issues Packages Projects Releases Wiki Activity

doc: add a manual page for rp(1)

Browse Source
This commit is contained in:
Emil Engler
2023-04-13 22:55:19 +02:00
committed by Karolin Varner
parent 838fd19694
commit 0456ded6b9
1 changed files with 115 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

115
doc/rp.1 Normal file
View File

@@ -0,0 +1,115 @@
.Dd $Mdocdate$
.Dt RP 1
.Os
.Sh NAME
.Nm rp
.Nd high-level interface to rosenpass
.Sh SYNOPSIS
.Nm
.Op Ar explain
.Op Ar verbose
.Ar genkey Ar ... | Ar pubkey ... | Ar exchange ...
.Nm
.Op ...
.Ar genkey PRIVATE_KEYS_DIR
.Nm
.Op ...
.Ar pubkey Ar PRIVATE_KEYS_DIR Ar PUBLIC_KEYS_DIR
.Nm
.Op ...
.\" Splitting this across several lines
.Ar exchange Ar PRIVATE_KEYS_DIR
.Op dev <device>
.Op listen <ip>:<port>
.\" Because the peer argument is complicated, it would be heel to represent it
.\" in mdoc... Using an ugly hack instead, thereby losing semantic.
[peer PUBLIC_KEYS_DIR [endpoint <ip>:<port>] [persistent-keepalive <interval>]
[allowed-ips <ip1>/<cidr1>[,<ip2>/<cidr2>] ...]] ...
.Sh DESCRIPTION
The
.Nm
program
is used to build a VPN with WireGuard and Rosenpass.
.Pp
The optional
.Op explain
and
.Op verbose
options can be used to obtain further help or to enable a detailed view on the
operations, respectively.
.Ss COMMANDS
.Bl -tag -width Ds
.It Ar genkey Ar PRIVATE_KEYS_DIR
Creates a new directory with appropriate permissions and generates all the
neccessary private keys required for a peer to participate in a rosenpass
connection.
.It Ar pubkey Ar PRIVATE_KEYS_DIR Ar PUBLIC_KEYS_DIR
Creates a fresh directory at
.Ar PUBLIC_KEYS_DIR ,
which contains the extracted public keys from the private keys generated by
.Ar genkey
and located inside
.Ar PRIVATE_KEYS_DIR .
.It Ar exchange Ar PRIVATE_KEYS_DIR [dev <device>] [listen <ip>:<port>] [PEERS]
Starts the VPN on interface
.Ar device ,
listening on the provided IP and port combination, allowing connections from
.Ar PEERS .
.El
.Sh EXIT STATUS
.Ex -std
.Sh EXAMPLES
To create a VPN connection, start by generating secret keys on both hosts.
.Bd -literal -offset indent
rp genkey server.rosenpass-secret
rp genkey client.rosenpass-secret
.Ed
.Pp
Extract the public keys:
.Bd -literal -offset indent
rp pubkey server.rosenpass-secret server.rosenpass-public
rp pubkey client.rosenpass-secret client.rosenpass-public
.Ed
.Pp
Copy the
.Qq -public
directories to the other peers and then start the VPN.
On the server:
.Bd -literal -offset indent
sudo rp exchange server.rosenpass-secret dev rosenpass0 listen 192.168.0.1:9999 \\
peer client.rosenpass-public allowed-ips fe80::/64
.Ed
.Pp
On the client:
.Bd -literal -offset indent
sudo rp exchange client.rosenpass-secret dev rosenpass 0 \\
peer server.rosenpass-public endpoint 192.168.0.1:9999 allowed-ips fe80::/64
.Ed
.Pp
Assign IP addresses:
.Bd -literal -offset indent
sudo ip a add fe80::1/64 dev rosenpass0 # Server
sudo ip a add fe80::2/64 dev rosenpass0 # Client
.Ed
.Pp
Test the connection by pinging the server on the client machine:
.Bd -literal -offset indent
ping fe80::1%rosenpass0 # Client
.Ed
.Pp
You can watch how rosenpass replaces the WireGuard PSK with the following:
.Bd -literal -offset indent
watch -n 0.2 'wg show all; wg show all preshared-keys'
.Ed
.Sh SEE ALSO
.Xr rosenpass 1 ,
.Xr wg 1
.Sh AUTHORS
Rosenpass was created by Karolin Varner, Benjamin Lipp, Wanja Zaeske,
Marei Peischl, Stephan Ajuvo, and Lisa Schmidt.
.Pp
This manual page was written by
.An Emil Engler
.Sh BUGS
The bugs are tracked at
.Lk https://github.com/rosenpass/rosenpass/issues .