From 793ef74ed60f6276dde4c7af2a06504037df7ca3 Mon Sep 17 00:00:00 2001 From: sommerfeld Date: Wed, 24 Apr 2024 15:27:02 +0100 Subject: Move man to root directory Otherwise Github Linguist does not pick it up as docs and the project looks like a Roff project ;) --- contrib/man/sentrum.1 | 552 -------------------------------------------------- 1 file changed, 552 deletions(-) delete mode 100644 contrib/man/sentrum.1 (limited to 'contrib/man/sentrum.1') diff --git a/contrib/man/sentrum.1 b/contrib/man/sentrum.1 deleted file mode 100644 index 932daca..0000000 --- a/contrib/man/sentrum.1 +++ /dev/null @@ -1,552 +0,0 @@ -.nh -.TH sentrum -.PP - - - - - -.PP -Daemon that monitors the Bitcoin blockchain for transactions involving your -wallets and sends you notifications in many different channels (ntfy push -notifications, email, telegram, nostr, arbitrary command, etc). - -.PP -Example screenshot of many noifications for a single transaction: - - - - -.SH Installation -.PP -Either: - -.RS -.IP \(bu 2 -Compile from source using \fBcargo install sentrum\fR (binary will be installed in -\fB~/.cargo/bin\fR) -.IP \(bu 2 -Download the binary from the -releases page -\[la]https://github.com/sommerfelddev/sentrum/releases\[ra] -.IP \(bu 2 -If using archlinux, install it from the AUR: -sentrum -\[la]https://aur.archlinux.org/packages/sentrum\[ra], -sentrum-bin -\[la]https://aur.archlinux.org/packages/sentrum\-bin\[ra] or -sentrum-git -\[la]https://aur.archlinux.org/packages/sentrum\-git\[ra] - -.RE - -.SH Configuration -.SS Config file path -.PP -It will look for a \fBsentrum.toml\fR configuration file located in any of these -directories (with this priority): - -.RS -.IP " 1." 5 -Current working directory -.IP " 2." 5 -\fB$XDG_CONFIG_HOME/sentrum\fR -.IP " 3." 5 -\fB~/.config/sentrum\fR -.IP " 4." 5 -\fB/etc/sentrum\fR (more appropriate if running as a systemd service) - -.RE - -.PP -Alternatively, you can pass the configuration file path as an argument in the -invocation and that will override any of the above. - -.PP -\fBStart by copying the sample configuration to where you want it.\fP E.g. - -.EX -cp sentrum.sample.toml sentrum.toml -sudo cp sentrum.sample.toml /etc/sentrum/sentrum.toml -.EE - -.PP -or - -.EX -sudo cp sentrum.sample.toml /etc/sentrum/sentrum.toml -.EE - -.SS What to configure -.PP -You can use the -\[la]sentrum.sample.toml\[ra] file as an -example. -Most options have very good defaults so you don't need to change them unless you -want to. \fBIn the examples below, commented options showcase their defaults, -unless explicitly said otherwise.\fP - -.SS Required -.RS -.IP \(bu 2 -\fBwallets\fR: what wallets you want to monitor -.IP \(bu 2 -\fBactions\fR: what actions you want to take once a relevant transaction is found - -.RE - -.SS Optional -.RS -.IP \(bu 2 -\fBelectrum\fR: by default, public electrum servers are used. You can configure it -to connect to your own -.IP \(bu 2 -\fBmessage\fR: this allows you to configure the subject and body templates of the -notification message and choose the relevant data from the transaction that -you want to include - -.RE - -.SH Wallets -.PP -For each wallet you want to track, add the following configuration: - -.EX -[[wallets]] -# Identifier for naming purposes (required) -name = "alice" -# Wallet xpub (required) -xpub = "xpub6CkXHzuU1NyHUFNiQZLq2bgt6QPqjZbwpJ1MDgDeo4bWZ8ZP7HZr7v9WTLCQFhxVhqiJNcw5wSKE77rkAK1SzcuHjt36ZUibBHezGzGL9h9" -# Script kind ("legacy","nested_segwit","segwit","taproot") (optional) -#kind = "segwit" -.EE - -.PP -It assumes a BIP84 (native segwit, \fBbc1\fR style addresses) wallet. If your wallet -has a different script kind add the field \fBkind = "legacy"\fR (or \fBnested_segwit\fR, -or \fBtaproot\fR). - -.PP -More complex wallet types are supported by providing \fBprimary = ""\fR and -\fBchange = ""\fR wallet descriptors instead of \fBxpub =\fR and \fBkind =\fR\&. - -.SH Actions -.PP -For each new relevant transaction, you can take multiple actions. For each -action you desire to take, you need to add the configuration: - -.EX -[[actions]] -# Action type (required) -type = "" -<.... INSERT ACTION SPECIFIC CONFIGURATION HERE...> -.EE - -.PP -Below we explain the configuration for each action kind. You can have multiple -actions of the same kind (e.g. you want to send multiple emails from different -accounts for some reason). - -.SS ntfy -.PP -This is the best straightforward way to get push notifications on a smartphone. - -.RS -.IP " 1." 5 -Install the android/iOS app following the relevant links in https://ntfy.sh -.IP " 2." 5 -If you don't run your own ntfy self-hosted server, create an account at -ntfy.sh -.IP " 3." 5 -Open the app, give it the needed permissions and configure your account -credentials -.IP " 4." 5 -Click on the \fB+\fR button and create a "topic", preferably named \fBsentrum\fR -since that's what will be used by default. - -.RE - -.PP -Then you just need to add the relevant configuration: - -.EX -[[actions]] -type = "ntfy" -# Credentials (required if you use a public server like the default one) -credentials.username = "" -credentials.password = "" -# ntfy server (optional) -#url = "https://ntfy.sh" -# notification channel name (optional) -#topic = "sentrum" -# Proxy used to connect (optional, defaults to None) -#proxy = "socks5://127.0.0.1:9050" -# Priority ("max", "high", "default", "low", "min") (optional) -#priority = "default" -.EE - -.SS nostr -.PP -Get notified by a nostr NIP04 encrypted -DM -\[la]https://github.com/nostr\-protocol/nips/blob/master/04.md\[ra] (leaks metadata -but widely supported) or a -NIP59 GiftWrap sealed sender DM -\[la]https://github.com/nostr\-protocol/nips/blob/master/59.md\[ra] -(more private but not supported by many clients). Add: - -.EX -[[actions]] -type = "nostr" -# Which npub to send the DM (required) -recipient = "" -# If NIP59 giftwrap DMs should be used instead of NIP04 (optional) -#sealed_dm = false -# Which relays to use to send DMs -#relays = ["wss://nostr.bitcoiner.social", "wss://nostr.oxtr.dev", "wss://nostr.orangepill.dev", "wss://relay.damus.io"] -.EE - -.SS email -.PP -You need to add the configuration below and essentially configure an -authenticated connection to your email provider's SMTP server. I cannot help you -out with every provider's weird rules (maybe you need to allow 3rd party apps -for gmail, who knows). - -.EX -[[actions]] -type = "email" -# SMTP server (required) -server = "\fR\&. - -.PP -You can pass the \fB--test\fR flag to send a single test notification to all -configured actions. - -.PP -By default, only new transactions can trigger actions. If you pass -\fB--notify-past-txs\fR, it will send notifications of past transactions -in the initial wallet sync. If you have a long transaction history, this will -spam your notification channels for every transaction. - -.SH systemd service -.PP -The ideal use-case is as a long running daemon, so it makes sense to configure -it as a systemd service. - -.PP -If you installed sentrum from the AUR, you just need to edit -\fB/etc/sentrum/sentrum.conf\fR and do \fBsudo systemclt enable --now sentrum.service\fR - -.PP -If you are installing \fBsentrum\fR manually (e.g. from the releases page or \fBcargo -install\fR), you should (either from the cloned repository or from inside the -extracted release archive): - -.RS -.IP " 1." 5 -Copy systemd files to appropriate places: - -.RE - -.EX -sudo cp contrib/systemd/sentrum.service -sudo cp contrib/systemd/sentrum.sysusers /etc/sysusers.d/sentrum.conf -sudo cp contrib/systemd/sentrum.tmpfiles /etc/tmpfiles.d/sentrum.conf -.EE - -.RS -.IP " 1." 5 -Reload systemd daemon, sysusers and tmpfiles: - -.RE - -.EX -sudo systemclt daemon-reload -sudo systemd-sysusers -sudo systemd-tmpfiles --create -.EE - -.RS -.IP " 1." 5 -Place the \fBsentrum.toml\fR (or \fBsentrum.sample.toml\fR) configuration file in -\fB/etc/sentrum\fR and make sure the \fBsentrum\fR user owns it: - -.RE - -.EX -sudo cp sentrum.toml /etc/sentrum -sudo chown sentrum:sentrum /etc/sentrum/sentrum.toml -.EE - -.RS -.IP " 1." 5 -Enable and start the service: - -.RE - -.EX -sudo systemclt enable --now sentrum.service -.EE - -.RS -.IP " 1." 5 -Check if everything is fine with \fBsystemctl status sentrum\fR -.IP " 2." 5 -Check the logs with \fBjournalctl -fu sentrum\fR - -.RE - -.SH Docker -.PP -To run sentrum using Docker, you can either build the image yourself or use the prebuilt image. - -.SS Building the image -.PP -To build the image from source, run the following: - -.EX -git clone https://github.com/sommerfelddev/sentrum.git -cd sentrum -docker build -t sentrum:local . -.EE - -.PP -To use the prebuilt image, simply pull from GHCR: - -.EX -docker pull docker pull ghcr.io/sommerfelddev/sentrum:latest -.EE - -.PP -Note that there are two types of tags: - -.PP -\fBlatest\fR: a tag from the latest commit to master -\fBx.x.x\fR: (i.e. \fB0.1.1\fR) a tag of the corresponding sentrum version - -.SS Running the image -.PP -To run the image, simply run the following, passing in the \fBsentrum.toml\fR file you created and configured earlier: - -.EX -docker run --rm -it --volume ./sentrum.toml:/sentrum.toml ghcr.io/sommerfelddev/sentrum:latest -.EE - -.PP -If using Docker compose, you can configure the service as follows: - -.EX -services: - sentrum: - container_name: sentrum - image: ghcr.io/sommerfelddev/sentrum:latest - restart: unless-stopped - volumes: - - ./sentrum.toml:/sentrum.toml -.EE - -.SH Future Work -.RS -.IP \(bu 2 -More action types: -.RS -.IP \(bu 2 -Matrix DM -.IP \(bu 2 -SimpleX chat DM -.IP \(bu 2 -IRC -.IP \(bu 2 -XMPP -.IP \(bu 2 -Whatsapp/Signal using linked devices (harder) -.IP \(bu 2 -HTTP request - -.RE - -.IP \(bu 2 -More wallet types: -.RS -.IP \(bu 2 -Single Address (blocked by -https://github.com/bitcoindevkit/bdk/issues/759) -.IP \(bu 2 -Collections of wallets as a single entity - -.RE - -.IP \(bu 2 -Notifications for the first tx confirmation and after N confirmations -.IP \(bu 2 -Filtering notifications by the transaction amounts (e.g. no action for -transactions smaller than 1M sats) -.IP \(bu 2 -Debian package (using \fBcargo-deb\fR) -.IP \(bu 2 -Allow per wallet actions -.IP \(bu 2 -Support other blockchain backends (bitcoind-rpc, explora, block filters, dojo) -.IP \(bu 2 -Maybe create a little web UI that helps with writing the configuration -.IP \(bu 2 -Incentivize node distributions to package sentrum - -.RE -- cgit v1.2.3-70-g09d2