mirror of
https://github.com/Coldcard/ckbunker.git
synced 2026-08-13 12:33:23 +02:00
Split out install
This commit is contained in:
Peter D. Gray
parent
66c804374e
commit
c29cb83fff
4 changed files with 142 additions and 90 deletions
|
|
@ -3,7 +3,8 @@
|
|||
|
||||
|
||||
- [Preview screencast (youtube)](https://www.youtube.com/watch?v=0bHhZbYOiSM)
|
||||
- [Documentation](https://ckbunker.com)
|
||||
- [Documentation (pretty)](https://ckbunker.com)
|
||||
- [Documentation (github)](docs/index.md)
|
||||
- [Usage examples and ideas](docs/examples.md) for HSM/CKBunker.
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -63,13 +63,13 @@ your Coldcard's wallets.
|
|||
|
||||
# Code Submission Guidelines
|
||||
|
||||
PR's are accepted but...
|
||||
PR's are welcome but...
|
||||
|
||||
- Please think of other users: don't remove existing use cases.
|
||||
- Don't add weird dependancies if easy to avoid.
|
||||
- Try to match existing coding style.
|
||||
- Large diffs are hard to accept with security-sensitive projects like this.
|
||||
- Please start your own fork and own it... we love that too!
|
||||
- Feel free to start your own fork and own it... we love that too!
|
||||
|
||||
|
||||
|
||||
|
|
|
|||
|
|
@ -7,8 +7,15 @@
|
|||
- [Documentation Website](https://ckbunker.com)
|
||||
- [Github for CKBunker](https://github.com/Coldcard/ckbunker).
|
||||
psbt.md
|
||||
- Full docs: [Setup Your Bunker](setup.md), [HSM Policy](policy.md), [PSBT Signing](psbt.md),
|
||||
[Message Signing](msg-signing.md), [Contributing Code](hacking.md)
|
||||
|
||||
## Full Documentation
|
||||
|
||||
1. [Installation](install.md)
|
||||
2. [Setup Bunker](setup.md)
|
||||
2. [HSM Policy](policy.md)
|
||||
2. [PSBT Signing](psbt.md)
|
||||
2. [Message Signing](msg-signing.md)
|
||||
2. [Contributing Code](hacking.md)
|
||||
|
||||
## What is the Coinkite Bunker?
|
||||
|
||||
|
|
@ -42,91 +49,6 @@ Learn more about the [Coldcard HSM-related features](https://coldcardwallet.com/
|
|||
[Follow @COLDCARDwallet on Twitter](https://twitter.com/coldcardwallet) to keep up
|
||||
with the latest updates and security alerts.
|
||||
|
||||
## Check-out and Setup
|
||||
|
||||
Do a checkout, recursively to get all the submodules:
|
||||
|
||||
git clone --recursive https://github.com/Coldcard/ckbunker.git
|
||||
|
||||
Then:
|
||||
|
||||
- `virtualenv -p python3 ENV` (Python 3.7 or higher is required)
|
||||
- `source ENV/bin/activate` (or `source ENV/bin/activate.csh` based on shell preference)
|
||||
- `pip install -r requirements.txt`
|
||||
- `pip install --editable .`
|
||||
|
||||
## Usage
|
||||
|
||||
The executable is called `ckbunker`:
|
||||
|
||||
```sh
|
||||
$ ckbunker --help
|
||||
Usage: ckbunker [OPTIONS] COMMAND [ARGS]...
|
||||
|
||||
Options:
|
||||
-s, --serial HEX Operate on specific unit (default: first found)
|
||||
--help Show this message and exit.
|
||||
|
||||
Commands:
|
||||
list List all attached Coldcard devices
|
||||
example Show an example config file, using the default values
|
||||
run Start the CKBunker for normal operation
|
||||
setup Configure your transaction signing policy, install it and then...
|
||||
```
|
||||
|
||||
There are two modes for the Bunker: "setup" and "run mode". In setup
|
||||
mode, Tor connections are disabled, as is the login screen. There is no
|
||||
security and it's meant for initial setup of the Coldcard and Bunker.
|
||||
|
||||
You would typically use the setup mode for picking the onion address, the
|
||||
master login password and all the details of the HSM policy.
|
||||
|
||||
```sh
|
||||
$ ckbunker setup
|
||||
```
|
||||
|
||||
Open this URL in your local web browser (must be same machine):
|
||||
<http://localhost:9823>
|
||||
|
||||
Once the Coldcard is running in HSM mode, with your policy installed,
|
||||
it makes sense to operate in normal "run" mode. This enables a simple
|
||||
login screen to keep out visitors:
|
||||
|
||||
```sh
|
||||
$ ckbunker run
|
||||
```
|
||||
|
||||
You may also run with remote connections (and login) disabled. This would be useful
|
||||
if you have some existing web proxy already in place.
|
||||
|
||||
```sh
|
||||
$ ckbunker --local run
|
||||
```
|
||||
|
||||
## Tor Use
|
||||
|
||||
To access over Tor as a hidden service, you must have `tord` running
|
||||
on the same machine. For desktop systems, keeping TorBrowser open
|
||||
is enough to acheive this. On servers, start tord with default options,
|
||||
and ckbunker will use the control port (localhost port 9051 or 9151).
|
||||
|
||||
If you use the bunker to broadcast the final (signed) transaction,
|
||||
the socks proxy of tord (port 9050) will also be used.
|
||||
|
||||
|
||||
## Operational Requirements
|
||||
|
||||
You will need:
|
||||
|
||||
- this code
|
||||
- a Mk3 Coldcard connected via USB, running
|
||||
[firmware version 3.1.0 or later](https://coldcardwallet.com/docs/upgrade)
|
||||
- `tord` (Tor program)
|
||||
- an Internet connection
|
||||
- a Tor-capable browser, like "Tor Browser" or Tails.
|
||||
- (optional) a microSD card, for logging of transactions on Coldcard
|
||||
- (optional, recommended) a mobile phone with TOTP 2FA app, like Google Authenticator or FreeOTP
|
||||
|
||||
## FAQ
|
||||
|
||||
### Will HSM mode be supported on Mk1 or Mk2?
|
||||
|
|
|
|||
129
docs/install.md
Normal file
129
docs/install.md
Normal file
|
|
@ -0,0 +1,129 @@
|
|||
# Installation
|
||||
|
||||
## Check-out and Setup
|
||||
|
||||
Do a checkout, recursively to get all the submodules:
|
||||
|
||||
git clone --recursive https://github.com/Coldcard/ckbunker.git
|
||||
|
||||
Then:
|
||||
|
||||
- `virtualenv -p python3 ENV` (Python 3.7 or higher is required)
|
||||
- `source ENV/bin/activate` (or `source ENV/bin/activate.csh` based on shell preference)
|
||||
- `pip install -r requirements.txt`
|
||||
- `pip install --editable .`
|
||||
|
||||
## Operational Requirements
|
||||
|
||||
You will need:
|
||||
|
||||
- this code (see above)
|
||||
- a Mk3 Coldcard connected via USB, running
|
||||
[firmware version 3.1.0 or later](https://coldcardwallet.com/docs/upgrade)
|
||||
- `tord` (Tor program)
|
||||
- an Internet connection
|
||||
- a Tor-capable browser, like "Tor Browser" or Tails.
|
||||
- (optional) a microSD card, for logging of transactions on Coldcard
|
||||
- (optional, recommended) a mobile phone with TOTP 2FA app, like Google Authenticator or FreeOTP
|
||||
|
||||
## Usage
|
||||
|
||||
The executable is called `ckbunker`:
|
||||
|
||||
```sh
|
||||
$ ckbunker --help
|
||||
Usage: ckbunker [OPTIONS] COMMAND [ARGS]...
|
||||
|
||||
Options:
|
||||
-s, --serial HEX Operate on specific unit (default: first found)
|
||||
--help Show this message and exit.
|
||||
|
||||
Commands:
|
||||
list List all attached Coldcard devices
|
||||
example Show an example config file, using the default values
|
||||
run Start the CKBunker for normal operation
|
||||
setup Configure your transaction signing policy, install it and then...
|
||||
```
|
||||
|
||||
There are two modes for the Bunker: "setup" and "run mode". In setup
|
||||
mode, Tor connections are disabled, as is the login screen. There is no
|
||||
security and it's meant for initial setup of the Coldcard and Bunker.
|
||||
|
||||
You would typically use the setup mode for picking the onion address, the
|
||||
master login password and all the details of the HSM policy.
|
||||
|
||||
```sh
|
||||
$ ckbunker setup
|
||||
```
|
||||
|
||||
Open this URL in your local web browser (must be same machine):
|
||||
<http://localhost:9823>
|
||||
|
||||
Once the Coldcard is running in HSM mode, with your policy installed,
|
||||
it makes sense to operate in normal "run" mode. This enables a simple
|
||||
login screen to keep out visitors:
|
||||
|
||||
```sh
|
||||
$ ckbunker run
|
||||
```
|
||||
|
||||
You may also run with remote connections (and login) disabled. This would be useful
|
||||
if you have some existing web proxy already in place.
|
||||
|
||||
```sh
|
||||
$ ckbunker --local run
|
||||
```
|
||||
|
||||
## Tor Use
|
||||
|
||||
To access over Tor as a hidden service, you must have `tord` running
|
||||
on the same machine. For desktop systems, keeping TorBrowser open
|
||||
is enough to acheive this. On servers, start tord with default options,
|
||||
and ckbunker will use the control port (localhost port 9051 or 9151).
|
||||
|
||||
If you use the bunker to broadcast the final (signed) transaction,
|
||||
the socks proxy of tord (port 9050) will also be used.
|
||||
|
||||
|
||||
|
||||
## Other Command Line Options
|
||||
|
||||
```sh
|
||||
% ckbunker run --help
|
||||
Usage: ckbunker run [OPTIONS]
|
||||
|
||||
Start the CKBunker for normal operation
|
||||
|
||||
Options:
|
||||
-l, --local Don't enable Tor (onion) access: just be on localhost
|
||||
-f, --psbt filename.psbt Preload first PSBT to be signed
|
||||
-c, --config-file FILENAME
|
||||
--help Show this message and exit.
|
||||
|
||||
```
|
||||
|
||||
You can specify a PSBT file for immediate use. That file will be "uploaded"
|
||||
and be ready to sign, but the system operates normally from there. You can
|
||||
upload further PSBT files and so on.
|
||||
|
||||
```sh
|
||||
% ckbunker setup --help
|
||||
Usage: ckbunker setup [OPTIONS]
|
||||
|
||||
Configure your transaction signing policy, install it and then operate.
|
||||
|
||||
Options:
|
||||
-l, --local Don't enable Tor (onion) access: just be on localhost
|
||||
-c, --config-file FILENAME
|
||||
--help Show this message and exit.
|
||||
```
|
||||
|
||||
Both forms take an optional config file. It's simple YAML and allows
|
||||
you to change the web server port number and similar values.
|
||||
The values that can be configured are defined in `persist.py` in
|
||||
the `Settings` class. See also `example-settings.yaml`.
|
||||
|
||||
|
||||
# Next Steps
|
||||
|
||||
[Bunker setup](setup.md)
|
||||
Loading…
Add table
Add a link
Reference in a new issue