Skip to content

Commit 3d771a4

Browse files
philpennockphilpennock
committed
Propose ADR-22: Client File Locations
1 parent c6fefec commit 3d771a4

File tree

3 files changed

+194
-2
lines changed

3 files changed

+194
-2
lines changed

‎README.md‎

Lines changed: 9 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,15 @@ This repo is used to capture architectural and design decisions as a reference o
2626
|[ADR-18](adr/ADR-18.md)|client|URL support for all client options|
2727
|[ADR-19](adr/ADR-19.md)|jetstream, client, kv, objectstore|API prefixes for materialized JetStream views:|
2828
|[ADR-20](adr/ADR-20.md)|jetstream, client, objectstore|JetStream based Object Stores|
29-
|[ADR-21](adr/ADR-21.md)|client|NATS Configuration Contexts|
29+
|[ADR-21](adr/ADR-21.md)|client, config|NATS Configuration Contexts|
30+
|[ADR-22](adr/ADR-22.md)|client, config|Client File Locations|
31+
32+
## Config
33+
34+
|Index|Tags|Description|
35+
|-----|----|-----------|
36+
|[ADR-21](adr/ADR-21.md)|client, config|NATS Configuration Contexts|
37+
|[ADR-22](adr/ADR-22.md)|client, config|Client File Locations|
3038

3139
## Jetstream
3240

‎adr/ADR-21.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
|Date |2021-12-14|
66
|Author |@ripienaar|
77
|Status |Partially Implemented|
8-
|Tags |client|
8+
|Tags |client, config|
99

1010
## Background
1111

‎adr/ADR-22.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,184 @@
1+
# Client File Locations
2+
3+
|Metadata|Value|
4+
|--------|-----|
5+
|Date |2022-01-24|
6+
|Author |@philpennock|
7+
|Status |Proposed|
8+
|Tags |client, config|
9+
10+
11+
## Context and Problem Statement
12+
13+
The configuration files for NATS clients should be in a coherent predictable location.
14+
Clients in various languages should be able to know where to read and write data,
15+
and administrators should know what file-system access is needed and where
16+
sensitive key data might be stored.
17+
18+
This document both unifies the location and acts as a living registry of the
19+
namespace within the NATS configuration directory.
20+
21+
22+
## Version History
23+
24+
|Date |Revision|
25+
|----------|--------|
26+
|2022-01-24|Initial proposal|
27+
28+
29+
## [Context | References | Prior Work]
30+
31+
* [ADR-21][] on Configuration Contexts moves us closer to the model
32+
described herein, but ADR-21 will need updating for the non-XDG platforms.
33+
* The `nsc` and `ngs` commands use other locations, scattering files around.
34+
* A Unix-centric model is the [XDG Base Directory Specification][xdgbase].
35+
36+
37+
## Design
38+
39+
We mandate a standard schema for where all NATS clients should lay out their
40+
configuration files, and guidance for migration and handling.
41+
42+
Our goals are:
43+
44+
1. Keep files of like type together, while adhering to OS norms.
45+
2. Never break existing user configuration.
46+
3. Register which files and sub-directories exist, to act as a central
47+
repository of such information, and record who can safely rely upon such
48+
details.
49+
50+
Rather than reinvent the wheel, we propose to use the layout schema of
51+
[Adrian-George Boston's Go implementation of XDG][adrg/xdg], which uses
52+
specific other locations for other operating systems, all documented in
53+
tables in the front README.
54+
55+
The documentation is specific enough to allow implementations in languages
56+
other than Go to use the same layouts. For Go, the `adrg/xdg` implementation
57+
has two dependencies, both of which we already depend upon in multiple
58+
`nats-io` repositories: `github.com/stretchr/testify` and `golang.org/x/sys`.
59+
The license is MIT and the code is stable but still seeing maintenance
60+
updates. It supports, “most flavors of Unix, Windows, macOS, and Plan 9”.
61+
62+
All configuration should live inside a directory called `nats`. Users should
63+
not need to learn which other tools might drop files elsewhere and should be
64+
able to, minimally, discover all the configuration by files or symbolic links
65+
within such directories. For configuration files, on Unix, this means that
66+
all per-tool configuration will be within the `~/.config/nats/` directory,
67+
while managed data might be within the `~/.local/share/nats/` directory.
68+
Environment variables and choice of OS will change that.
69+
70+
71+
### Migration
72+
73+
Much of the existing client configuration involves authentication data such as
74+
NKeys or combined `.creds` files. These are more likely than most to have
75+
been moved by the users to secure storage and replaced with symbolic links or
76+
be on encrypted mounts. As such, automatically migrating such data is fraught
77+
with peril.
78+
79+
For the time being, we instead simply mandate that files be accessible by the
80+
new paths; it is acceptable for client libraries to detect that the new
81+
location does not exist on disk but the old location does exist, and put in a
82+
symbolic link at the new location pointing to the old location.
83+
84+
Ideally, the users will migrate their data to clean up the symbolic links.
85+
86+
At a later date, we _might_ choose to automatically migrate files, as long as
87+
a sweep of the old location confirms that all entries are files or
88+
directories, free of symlinks, and all on the same file-system.
89+
90+
In the below descriptions of old locations, a phrase "unless overridden by an
91+
environment variable" would be needed in many places to strictly cover all
92+
contingencies; for clarity in the prose, we omit that to just describe the
93+
defaults.
94+
Similarly, unless specifically addressing an operating system, we'll use the
95+
XDG locations for examples.
96+
97+
### The `nats` CLI
98+
99+
The `nats` CLI uses the XDG location logic, in a simplified form, so the data
100+
has until now been written to `~/.config/nats/` always. On Unix systems this
101+
remains valid; on other systems supporting symbolic links, we should point to
102+
that location.
103+
104+
The `nats` CLI has proven the utility of the configuration model we're moving
105+
to.
106+
107+
The configuration used by the `nats` CLI are the configuration contexts, which
108+
are generic for client tooling and not specific to that tool, so we consider
109+
the `context/` directory and `context.txt` file to be top-level configuration
110+
items.
111+
112+
### The `nsc` CLI
113+
114+
The default locations of files for `nsc` can be overridden with the
115+
environment variables: `$NSC_HOME`, `$NKEYS_PATH`, and `$NSC_CWD_ONLY`.
116+
117+
In addition, `nsc` has traditionally detected an account system Operator in
118+
the current directory and then ignored all environment variables to use the
119+
current directory as a root.
120+
This behavior is considered an authentication administrator mode and should
121+
not be used by most tools.
122+
123+
Existing client tools should continue to honor `$NSC_HOME` and `$NKEYS_PATH`
124+
to avoid breaking scripts, but new client tools should not use those
125+
variables.
126+
127+
These files all now are under the ownership of the `nsc` concept, so live in
128+
the `nsc/` sub-directory of the NATS locations.
129+
130+
The old file `~/.nsc/nsc.json` is configuration and so would live under
131+
`$XDG_CONFIG_HOME` or equivalent. Thus on Unix, `~/.config/nats/nsc/nsc.json`
132+
should be used.
133+
134+
The credentials and nkeys files are considered data, and so will live under
135+
`~/.local/share/nats/nsc/stores/` and `~/.local/share/nats/nsc/nkeys/`.
136+
137+
138+
### Other environment variables not yet pulled in
139+
140+
Some client tools support `$NATS_KEY` and `$NATS_CERT` to refer to client
141+
X.509 keys and certificates.
142+
143+
## Consequences
144+
145+
At some point in the future, we should attempt to migrate existing files in
146+
their old locations to the new standard locations. We should leave behind
147+
symbolic links in "the other direction" to prevent breakage.
148+
149+
We should never remove the symbolic links from the old locations, it's up to
150+
the users/administrators to do so when they're happy to do so.
151+
152+
153+
## Registry
154+
155+
* Configuration
156+
+ The `context/` directory and `context.txt` file are used as per [ADR-21][]
157+
for configuration contexts.
158+
- Library implementations of contexts should be aware of this.
159+
- Most applications should avoid assumptions.
160+
- Contexts can contain sensitive data, where a server uses password-based
161+
authentication.
162+
- compatibility location: strict XDG adherence on all platforms.
163+
+ The `nsc/` and `nkeys/` directories are reserved for client credentials
164+
and the account system, as described above.
165+
- Most tools should not need to be specifically aware in code of the
166+
location of these; where credentials are passed in, they are typically
167+
part of the site configuration.
168+
- New tools should use [ADR-21][] configuration contexts to locate
169+
relevant data.
170+
- The `nkeys/` directory and `nsc/creds/` directory both contain sensitive
171+
client secrets and should be protected. When creating these
172+
directories, or files within, permissions should be set to be tighter
173+
than the "umask", permitting access only for the user.
174+
+ The `ngs/` directory is reserved for use by one of the corporate
175+
maintainers of NATS, Synadia Communications.
176+
177+
178+
<!-- Markdown References: -->
179+
180+
[ADR-21]: ADR-21.md
181+
[adrg/xdg]: https://github.com/adrg/xdg
182+
"Adrian-George Bostan's implementation of XDG in Go"
183+
[xdgbase]: https://specifications.freedesktop.org/basedir-spec/basedir-spec-latest.html
184+
"XDG Base Directory Specification"

0 commit comments

Comments
 (0)