Skip to content

Commit d5dce7d

Browse files
philpennockphilpennock
committed
Propose ADR-22: Client File Locations
This documents a combination of existing practice of some clients and an optimal New World Order to better support Windows, to try to get something well documented for all clients to adhere to.
1 parent e7d46cf commit d5dce7d

File tree

3 files changed

+207
-2
lines changed

3 files changed

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

0 commit comments

Comments
 (0)