1# Setup 2 3## Table of Contents 4 51. [Pre-Installation Steps](#pre-installation-steps) 62. [Installation Steps](#installation-steps) 73. [Optional Post-Installation Steps](#optional-post-installation-steps) 84. [Using gopass](#using-gopass) 9 10## Pre-Installation Steps 11 12### Download and Install Dependencies 13 14gopass needs some external programs to work: 15 16* `gpg` - [GnuPG](https://www.gnupg.org/), preferably in Version 2 or later 17* `git` - [Git SCM](https://git-scm.com/), any Version should be OK 18 19It is recommended to have either `rng-tools` or `haveged` installed to speed up 20key generation if these are available for your platform. 21 22#### Ubuntu & Debian 23 24```bash 25apt-get update 26apt-get install gnupg2 git rng-tools 27``` 28 29_Note:_ installing on Ubuntu prior to 16.04 and similarly old Debian versions might require you to install `gnupg` instead of `gnupg2`. 30 31#### RHEL & CentOS 32 33```bash 34yum install gnupg2 git rng-tools 35``` 36 37#### Arch Linux 38 39```bash 40pacman -S gnupg2 git rng-tools 41``` 42 43#### MacOS 44 45If you haven't already, install [homebrew](http://brew.sh). And then: 46 47```bash 48brew install gnupg2 git 49``` 50 51#### Windows 52 53* Download and install [GPG4Win](https://www.gpg4win.org/). 54* Download and install [the Windows git installer](https://git-scm.com/download/win). 55 56Alternatively, it can be installed via [chocolatey](https://chocolatey.org/packages/gopass) 57 58* `choco install gopass` (requires admin privileges) 59 60#### OpenBSD 61 62For OpenBSD -current: 63``` 64pkg_add gopass 65``` 66 67For OpenBSD 6.2 and earlier, install via `go get`. 68 69Please note that the OpenBSD builds uses `pledge(2)` to disable some syscalls, 70so some features (e.g. version checks, auto-update) are unavailable. 71 72### Set up a GPG key pair 73 74gopass depends on the `gpg` program for encryption and decryption. You **must** have a 75suitable key pair. To list your current keys, you can do: 76 77```bash 78gpg --list-secret-keys 79``` 80 81If there is no output, then you don't have any keys. To create a new key: 82 83```bash 84gpg --full-generate-key 85``` 86 87You will be presented with several options: 88 89* Key type: Choose either "RSA and RSA" or "DSA and ElGamal". 90* Key size: Choose at least 2048. 91* Validity: 5 to 10 years is a good default. 92* Enter your real name and primary email address. 93* A comment is not necessary. 94* Pass phrase: Make sure to pick a very long pass phrase, not just a simple password. Remember this should be stronger than any of the secrets you store in the password store. You can configure the GPG Agent later to save you repetitive typing. 95 96Now, you have created a public and private key pair. If you don't know what that means, or if you are not familiar with GPG, we highly recommend you do a little reading on the subject. Check out the following manuals: 97 98* ["git + gpg, know thy commits" at coderwall](https://coderwall.com/p/d3uo3w/git-gpg-know-thy-commits) 99* ["Generating a new GPG key" by GitHub](https://help.github.com/articles/generating-a-new-gpg-key/) 100 101### Git and GPG 102 103gopass will configure git to sign commits by default, so you should make sure that git can 104interface with GPG. 105 106```bash 107mkdir some-dir 108cd some-dir 109git init 110touch foo 111git add foo 112git commit -S -m "test" 113``` 114Here the `-S` flag will sign your commit using GPG, allowing you to test your GPG setup with git. 115If you get an error like: "gpg failed to sign the data" try to see if creating a clear text signature works: 116 117```bash 118 echo "test" | gpg2 --clearsign 119``` 120 121If this fails with an error: "Inappropriate ioctl for device" run the following command: 122 123```bash 124 export GPG_TTY=$(tty) 125``` 126Now you should be able to create a clear text signature and the commit should work flawlessly. 127 128If you are presented with a different error please investigate this before continuing. If that works 129set it in your `.zprofile`, `.bashrc` or simliar. 130 131Also if you have both `gnupg` and `gnupg2` installed, make sure to use the latter in git: 132```bash 133git config --global gpg.program gpg2 134``` 135 136## Installation Steps 137 138Depending on your operating system, you can either use a package manager, download a pre-built binary, or install from source. If you have a working Go development environment, we recommend building from source. 139 140### MacOS 141 142If you haven't already, install [homebrew](http://brew.sh). And then: 143 144```bash 145brew install gopass 146``` 147 148Alternatively, you can install gopass from the appropriate Darwin release from the repository [releases page](https://github.com/gopasspw/gopass/releases). 149 150If you're using a password on your GPG key, you also have to install `pinentry-mac` from brew and configure it in your `~/gpg/gpg-agent.conf`: 151 152```bash 153brew install pinentry-mac 154PINENTRY=$(which pinentry-mac) 155echo "pinentry-program ${PINENTRY}" >>~/.gnupg/gpg-agent.conf 156``` 157 158### Ubuntu, Debian, Deepin, Devuan, Kali Linux, Pardus, Parrot, Raspbian 159 160**WARNING**: The official Debian repositories (and derived distributions) contain 161a package named `gopass` that is not related to this project in any way. 162It's a similar tool with a completely independent implementation and feature set. 163We are aware of this issue but can not do anything about it. 164 165When installing on Ubuntu or Debian you can either download the `deb` package 166and [install manually or build from source](#installing-from-source). 167 168#### Manual download 169 170First, find the latest .deb release from the repository [releases page](https://github.com/gopasspw/gopass/releases). Then, download and install it: 171 172```bash 173wget [the URL of the latest .deb release] 174sudo dpkg -i gopass-1.2.0-linux-amd64.deb 175``` 176 177### Gentoo 178 179There is an overlay that includes gopass. Run these commands to install gopass through `emerge`. 180 181```bash 182layman -a go-overlay 183emerge -av gopass 184``` 185 186### Fedora / Red Hat / CentOS 187 188There is an unofficial RPM build maintained by a contributor. 189 190```bash 191# if you're using dnf (needs dnf-plugins-core) 192dnf copr enable daftaupe/gopass 193dnf install gopass 194# of if you're using an older distribution (needs yum-plugin-copr) 195yum copr enable daftaupe/gopass 196yum install gopass 197``` 198 199### Arch Linux 200```bash 201pacman -S gopass 202``` 203 204 205### Windows 206 207**WARNING**: Windows is not yet officially supported. We try to support it in the future. These are steps are only meant to help you setup gopass on Windows so you can provide us with feedback about the current state of our Windows support. 208 209You can install `gopass` by [Chocolatey](https://chocolatey.org/): 210 211```bash 212choco install gopass 213``` 214 215Or by [Scoop](https://scoop.sh/): 216 217```bash 218scoop install gopass 219``` 220 221Alternatively, download and install a suitable Windows build from the repository [releases page](https://github.com/gopasspw/gopass/releases). 222 223### Installing from Source 224 225If you have [Go](https://golang.org/) already installed, you can use `go get` to automatically download the latest version: 226 227```bash 228GO111MODULE=on go get -u github.com/gopasspw/gopass 229``` 230 231If `$GOPATH/bin` is in your `$PATH`, you can now run `gopass` from anywhere on your system. 232 233## Optional Post-Installation Steps 234 235### Securing Your Editor 236 237Various editors may store temporary files outside of the secure working directory when editing secrets. We advise you to check and disable this behavior for your editor of choice. 238 239For `vim` on Linux, the following setting may be helpful: 240 241``` 242au BufNewFile,BufRead /dev/shm/gopass.* setlocal noswapfile nobackup noundofile 243``` 244 245For MacOS consider this setting: 246 247``` 248au BufNewFile,BufRead /private/**/gopass** setlocal noswapfile nobackup noundofile 249``` 250 251### Migrating from pass to gopass 252 253If you are migrating from pass to gopass, you can simply use your existing password store and everything should just work. Furthermore, it may be helpful to link the gopass binary so that you can use it as a drop-in replacement. For example, assuming `$HOME/bin/` exists and is present in your `$PATH`: 254 255```bash 256ln -s $GOPATH/bin/gopass $HOME/bin/pass 257``` 258 259### Migrating to gopass from Other Password Stores 260 261Before migrating to gopass, you may have been using other password managers (such as [KeePass](https://keepass.info/), for example). If you were, you might want to import all of your existing passwords over. Because gopass is fully backwards compatible with pass, you can use any of the existing migration tools found under the "Migrating to pass" section of the [official pass website](https://www.passwordstore.org/). 262 263### Enable Bash Auto completion 264 265If you use Bash, you can run one of the following commands to enable auto completion for sub-commands like `gopass show`, `gopass ls` and others. 266 267```bash 268source <(gopass completion bash) 269``` 270 271**MacOS**: The version of bash shipped with MacOS may [require a workaround](https://stackoverflow.com/questions/32596123/why-source-command-doesnt-work-with-process-substitution-in-bash-3-2) to enable auto completion. If the instructions above do not work try the following one: 272 273```bash 274source /dev/stdin <<<"$(gopass completion bash)" 275``` 276 277### Enable Z Shell Auto completion 278 279If you use zsh, `make install` or `make install-completion` should install the completion in the correct location. 280 281If zsh autocompletion is still not functional, or if you want to install it manually, you can run the following commands: 282 283```bash 284$ gopass completion zsh > ~/_gopass 285$ sudo mv ~/_gopass /usr/share/zsh/site-functions/_gopass 286$ rm -i ${ZDOTDIR:-${HOME:?No ZDOTDIR or HOME}}/.zcompdump && compinit 287 288``` 289Then exit and re-run zsh if the last command failed. 290 291Notice that it is important to directly redirect Gopass' output to a file, 292using pipes or echo mess up the output. Also notice that the generated `_gopass` file is 293a completion file that is supposed to be handled by zsh and to be installed in the zsh 294completions directory, as defined by either the standard `/usr/share/zsh/site-functions/` path, 295or by a user-specified `fpath` folder. It is not meant to used with `source`. 296 297If zsh completion is still not working, you might want to add the following to your `.zshrc` file: 298```bash 299autoload -U compinit && compinit 300``` 301if you don't have it already. 302 303### Enable fish completion 304 305If you use the [fish](https://fishshell.com/) shell, you can enable experimental shell completion by the following command: 306```fish 307$ mkdir -p ~/.config/fish/completions and; gopass completion fish > ~/.config/fish/completions/gopass.fish 308``` 309and start a new shell afterwards. 310 311Since writing fish completion scripts is not yet supported by the CLI library we use, this completion script is missing a few features. Feel free to contribute if you want to improve it. 312 313### dmenu / rofi support 314 315In earlier versions gopass supported [dmenu](http://tools.suckless.org/dmenu/). We removed this and encourage you to call dmenu yourself now. 316 317This also makes it easier to call gopass with any drop-in replacement of dmenu, like [rofi](https://github.com/DaveDavenport/rofi), for example, since you would just need to replace the `dmenu` call below by `rofi -dmenu`. 318 319```bash 320# Simply copy the selected password to the clipboard 321gopass ls --flat | dmenu | xargs --no-run-if-empty gopass show -c 322# First pipe the selected name to gopass, decrypt it and type the password with xdotool. 323gopass ls --flat | dmenu | xargs --no-run-if-empty gopass show -o | xdotool type --clearmodifiers --file - 324# First pipe the selected name to gopass, and type the value from the key "username" with xdotool. 325gopass ls --flat | dmenu | xargs --no-run-if-empty -- bash -c 'gopass show -f $0 username' | head -n 1 | xdotool type --clearmodifiers --file - 326# Oterwise type the name of the entry using xdotool, in case you are not including a username key in your entries 327gopass ls --flat | dmenu | sed 's!.*/!!' | tr -d '\n' | xdotool type --clearmodifiers --file - 328``` 329 330You can then bind these command lines to your preferred shortcuts in your window manager settings, typically under `System Settings > Keyboard > Shortcuts > Custom Shortcuts`. In some cases you may need to wrap it with `bash -c 'your command'` in order for it to work (tested and working in Ubuntu 18.04). 331 332### Filling in passwords from browser 333 334Gopass allows filling in passwords in browsers leveraging a browser plugin like [gopass bridge](https://github.com/gopasspw/gopassbridge). 335The browser plugin communicates with gopass-jsonapi via JSON messages. 336To allow the plugin to start gopass-jsonapi, a [native messaging manifest](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Native_messaging) must be installed for each browser. 337Chrome, Chromium and Firefox are supported, currently. 338 339**Upgrade to gopass v1.10 / v1.11**: 340`gopass-jsonapi` is now its own binary file, which you need to install separately. 341 342The binary for v1.10 and v1.11 can be downloaded and unpacked from 343[archive files on Github Releases](https://github.com/gopasspw/gopass/releases/tag/v1.11.0). 344 345You need to run `gopass-jsonapi configure` after the upgrade to configure your browser for the new command. 346 347**Upgrade to gopass v1.12** 348The new binary can be downloaded from the latest 349[Github Release on gopass-jsonapi](https://github.com/gopasspw/gopass-jsonapi/releases). 350 351For more detailed instructions, please read: [gopass-jsonapi/README](https://github.com/gopasspw/gopass-jsonapi/blob/main/README.md). 352 353### Storing and Syncing your Password Store with git 354 355This is the recommended way to use `gopass`. 356 357NOTE: We do recommend to use a private Git repository. A public one will keep 358your credentials secure but it will leak metadata. 359 360To use `gopass` with `git` either create a new git repository or clone an existing 361password store. 362 363#### New password store with git 364 365Create a new repository, either locally or on a server, then specify this 366repository during the `gopass setup`. 367 368```bash 369$ gopass setup --crypto gpg --storage gitfs # used by default 370[...] 371# provide an existing, empty git remote, e.g. git@gitlab.example.org:john/passwords.git 372``` 373 374#### Existing password store with git 375 376If you have created a password store with `git`, `gopass` can easily clone it. 377 378```bash 379$ gopass clone git@gitlab.example.org:john/passwords.git 380``` 381 382### Storing and Syncing your Password Store with Google Drive / Dropbox / Syncthing / etc. 383 384The recommended way to use Gopass is to sync your store with a git repository, preferably a private one, since the name and path of your secrets might reveal information that you'd prefer to keep private. 385However, shall you prefer to, you might also use the `noop` storage backend that is meant to store data on a cloud provider instead of a git server. 386 387Please be warned that using cloud-based storage may negatively impact the confidentiality of your store. However, if you wish to use one of these services, you can do so. 388 389For example, to use gopass with [Google Drive](https://drive.google.com): 390 391```bash 392gopass setup --storage fs 393mv .password-store/ "Google Drive/Password-Store" 394gopass config path "~/Google Drive/Password-Store" 395``` 396 397### Download a GUI 398 399Because gopass is fully backwards compatible with pass, you can use some existing graphical user interfaces / frontends: 400 401* Android - [PwdStore](https://github.com/zeapo/Android-Password-Store) 402* iOS - [Pass for iOS](https://github.com/davidjb/pass-ios#readme) 403* Windows / MacOS / Linux - [QtPass](https://qtpass.org/) 404 405There is also [Gopass UI](https://github.com/codecentric/gopass-ui) which was exclusively implemented for gopass and is available for MacOS, Linux and Windows. 406 407Others can be found at the "Compatible Clients" section of the [official pass website](https://www.passwordstore.org/). 408 409## Using gopass 410 411Once you have installed gopass, check out the [features documentation](https://github.com/gopasspw/gopass/blob/master/docs/features.md) for some quick usage examples. 412 413### Using the onboarding wizard 414 415Running `gopass` with no existing store will start the onboarding wizard which 416will guide you through the setup of gopass. 417 418### Batch bootstrapping 419 420In order to simplify the setup of gopass for your team members it can be run in a fully scripted bootstrap mode. 421 422```bash 423# First initialize a new shared store and push it to an empty remote 424gopass --yes setup --remote github.com/example/pass.git --alias example --create --name "John Doe" --email "john.doe@example.com" 425 426# For every other team member initialize a new store and clone the existing remote 427gopass --yes setup --remote github.com/example/pass.git --alias example --name "Jane Doe" --email "jane.doe@example.com" 428``` 429 430The first command will create a new mount named `example` and push it to an empty (`--create`) remote. 431It will fail if the remote at `github.com/example/pass.git` is not empty. 432 433The second command will clone the existing (no `--create` flag) remote `github.com/example/pass.git` 434and mount it as the mount point `example`. 435 436