-
Notifications
You must be signed in to change notification settings - Fork 0
/
vkv.1
159 lines (116 loc) · 5.24 KB
/
vkv.1
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
.TH VKV 1 2024-01-15 "vkv (git)" "user commands"
.\" ============================================================================
.\" disable hyphenation, left-align
.nh
.ad l
.\" ============================================================================
.SH NAME
vkv - minimalistic commandline interface for getting KV secrets from HashiCorp
Vault
.\" ============================================================================
.SH SYNOPSIS
\fBvkv -h\fR
.br
\fBvkv\fR [\fIoptions\fR...] \fIcommand\fR [\fIargs\fR...]
.\" ============================================================================
.SH DESCRIPTION
vkv allows fetching secrets from a HashiCorp Vault (or compatible) key-value
(KV) store in a way similar to \fBpass\fR(1).
vkv itself does not store any secrets, but it allows "bookmarking" paths to
secrets in the KV store, for easier reuse (see \fBFILES\fR below).
.SS Options
.TP 4
\fB-d\fR
Print debug messages to \fBstderr\fR during execution (e.g. JSON responses).
.TP
\fB-h\fR
Print a help message and exit.
.SS Commands
vkv's functionality is split up into multiple commands, each described in this
section. In addition to the options described below, each command also accepts
\fB-h\fR for showing a command-specific help message.
.TP 4
\fBlist\fR
List all bookmarked KV paths. The bookmark file is described in the \fBFILES\fR
section below.
.TP
\fBshow\fR [\fB-c\fR] \fIkvpath\fR \fIfield\fR [\fIfilter\fR...]
Show the content of a secret's field in the KV store. \fIkvpath\fR denotes the
secret's path; it is described in the \fBKV PATHS\fR section below. \fIfield\fR
denotes the field to be selected within the secret. The optional \fIfilter\fR
arguments verify that the other fields in the secret contain expected values;
the format is described in the \fBFILTER FORMAT\fR section below. If \fB-c\fR is
passed, the secret is copied to the X11 clipboard instead of being printed to
\fBstdout\fR; see the section \fBCLIPBOARD\fR below for more details.
.\" ============================================================================
.SH KV PATHS
Some commands take the KV path of a secret, which must be formated as follows:
.RS 4
\fImount\fB/\fIpath\fR
.RE
i.e. the first element of the path is split and interpreted as the KV v2
mountpoint of the KV store. The remainder is taken as a path within that store.
.\" ============================================================================
.SH FILTER FORMAT
A filter (used for the \fBshow\fR command) is of the following form:
.RS 4
\fIkey\fB=\fIvalue\fR
.RE
This instructs \fBshow\fR to verify that the field \fIkey\fR contains the value
\fIvalue\fR and error out if the found value differs.
This allows for example to ensure that a \fBusername\fR field contains the
expected username for a requested \fBpassword\fR field. The following example
shows a case where we want the password for a \fBweb.example.net\fR login, but
only if the username is \fBwebmaster\fR, as expected:
.RS 4
\fBvkv show mykvstore/service/web.example.net/admin password username=webmaster\fR
.RE
.\" ============================================================================
.SH ENVIRONMENT VARIABLES
The following environment variables influence the behaviour of vkv:
.TP 4
\fBUSER\fR
Username on the system. If unset, \fBid\fR(1p) is used to determine the
username.
.TP
\fBHOME\fR
Location of user files. If unset, the user's \fBpasswd\fR(5) entry is used to
determine the home directory.
.TP
\fBXDG_CONFIG_HOME\fR
Location of user configuration files (see also \fBFILES\fR below). If unset, the
default \fB~/.config\fR is used in accordance with the XDG base directory
specification.
.TP
\fBPASSWORD_STORE_X_SELECTION\fR
X11 selection to be used for storing the secret with \fBshow -c\fR. Possible
values are described in \fBxclip\fR(1), for the \fB-selection\fR option. The
default is \fBclipboard\fR.
.TP
\fBVAULT_ADDR\fR
Address to the HashiCorp Vault instance containing the secret.
.PP
Note that other \fBVAULT_…\fR environment variables may need to be set,
depending on your local HashiCorp Vault setup.
.\" ============================================================================
.SH FILES
.TP 4
\fI$XDG_CONFIG_HOME\fB/vkv/paths\fR
"Booksmarks" file containing a list of KV paths. This is listed by the
\fBlist\fR command, which is also consumed by helper utilities like
\fBvkvmenu\fR(1). Each line must contain the arguments for a \fBshow\fR
invocation. Empty lines and lines starting with \fB#\fR are ignored.
.\" ============================================================================
.SH LIMITATIONS
This utility is very minimalistic and not optimised for manual use. Instead,
users are advised to use the \fBvkvmenu\fR(1) utility, an interactive menu for
selecting secrets similar to \fBpassmenu\fR.
It also currently assumes the executable to be named \fBvault\fR. Any compatible
tool (like OpenBao) must therefore provide that command in \fI$PATH\fR, for
instance with a shim executable or a compatibility symlink.
.\" ============================================================================
.SH SEE ALSO
\fBvkvmenu\fR(1), \fBpass\fR(1) (\fBpassmenu\fR), \fBxclip\fR(1)
.\" ============================================================================
.SH BUGS
Please report bugs on https://github.com/martinwe-adfinis/vkv/issues.