ttlama-cli 0.1.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- ttlama_cli-0.1.0/LICENSE +71 -0
- ttlama_cli-0.1.0/PKG-INFO +310 -0
- ttlama_cli-0.1.0/README.md +281 -0
- ttlama_cli-0.1.0/pyproject.toml +46 -0
- ttlama_cli-0.1.0/setup.cfg +4 -0
- ttlama_cli-0.1.0/src/ttlama_cli/__init__.py +0 -0
- ttlama_cli-0.1.0/src/ttlama_cli/__main__.py +6 -0
- ttlama_cli-0.1.0/src/ttlama_cli/api_client.py +221 -0
- ttlama_cli-0.1.0/src/ttlama_cli/cli.py +71 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/__init__.py +256 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/admin/__init__.py +22 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/admin/devices.py +300 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/admin/leases.py +244 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/admin/profiles.py +328 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/admin/users.py +460 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/auth.py +469 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/backend/__init__.py +18 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/backend/openvpn/__init__.py +0 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/backend/openvpn/peers.py +0 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/backend/wireguard/__init__.py +18 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/backend/wireguard/peers.py +282 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/config.py +350 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/user/__init__.py +29 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/user/devices.py +214 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/user/get.py +95 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/user/leases.py +223 -0
- ttlama_cli-0.1.0/src/ttlama_cli/commands/user/profiles.py +84 -0
- ttlama_cli-0.1.0/src/ttlama_cli/config_store.py +109 -0
- ttlama_cli-0.1.0/src/ttlama_cli/drivers/__init__.py +19 -0
- ttlama_cli-0.1.0/src/ttlama_cli/drivers/_common.py +116 -0
- ttlama_cli-0.1.0/src/ttlama_cli/drivers/openvpn.py +59 -0
- ttlama_cli-0.1.0/src/ttlama_cli/drivers/wireguard.py +165 -0
- ttlama_cli-0.1.0/src/ttlama_cli/exc.py +78 -0
- ttlama_cli-0.1.0/src/ttlama_cli/objects/__init__.py +18 -0
- ttlama_cli-0.1.0/src/ttlama_cli/objects/requests.py +65 -0
- ttlama_cli-0.1.0/src/ttlama_cli/token_store.py +85 -0
- ttlama_cli-0.1.0/src/ttlama_cli/utils.py +30 -0
- ttlama_cli-0.1.0/src/ttlama_cli.egg-info/PKG-INFO +310 -0
- ttlama_cli-0.1.0/src/ttlama_cli.egg-info/SOURCES.txt +53 -0
- ttlama_cli-0.1.0/src/ttlama_cli.egg-info/dependency_links.txt +1 -0
- ttlama_cli-0.1.0/src/ttlama_cli.egg-info/entry_points.txt +2 -0
- ttlama_cli-0.1.0/src/ttlama_cli.egg-info/requires.txt +14 -0
- ttlama_cli-0.1.0/src/ttlama_cli.egg-info/top_level.txt +1 -0
- ttlama_cli-0.1.0/tests/test_admin_devices_commands.py +334 -0
- ttlama_cli-0.1.0/tests/test_admin_leases_commands.py +230 -0
- ttlama_cli-0.1.0/tests/test_admin_profiles_commands.py +262 -0
- ttlama_cli-0.1.0/tests/test_admin_users_commands.py +359 -0
- ttlama_cli-0.1.0/tests/test_api_client.py +230 -0
- ttlama_cli-0.1.0/tests/test_auth_commands.py +679 -0
- ttlama_cli-0.1.0/tests/test_cli.py +503 -0
- ttlama_cli-0.1.0/tests/test_config_store.py +52 -0
- ttlama_cli-0.1.0/tests/test_global_config_commands.py +115 -0
- ttlama_cli-0.1.0/tests/test_token_store.py +48 -0
- ttlama_cli-0.1.0/tests/test_user_commands.py +160 -0
- ttlama_cli-0.1.0/tests/test_user_resource_commands.py +259 -0
ttlama_cli-0.1.0/LICENSE
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# Apache License
|
|
2
|
+
|
|
3
|
+
English | [Français](./docs/LICENSE.fr.md)
|
|
4
|
+
|
|
5
|
+
Version 2.0, January 2004
|
|
6
|
+
<http://www.apache.org/licenses/>
|
|
7
|
+
|
|
8
|
+
## TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
|
9
|
+
|
|
10
|
+
### 1. Definitions
|
|
11
|
+
|
|
12
|
+
"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
|
|
13
|
+
|
|
14
|
+
"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
|
|
15
|
+
|
|
16
|
+
"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
|
|
17
|
+
|
|
18
|
+
"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
|
|
19
|
+
|
|
20
|
+
"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
|
|
21
|
+
|
|
22
|
+
"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
|
|
23
|
+
|
|
24
|
+
"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
|
|
25
|
+
|
|
26
|
+
"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
|
|
27
|
+
|
|
28
|
+
"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
|
|
29
|
+
|
|
30
|
+
"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
|
|
31
|
+
|
|
32
|
+
### 2. Grant of Copyright License
|
|
33
|
+
|
|
34
|
+
Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
|
|
35
|
+
|
|
36
|
+
### 3. Grant of Patent License
|
|
37
|
+
|
|
38
|
+
Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
|
|
39
|
+
|
|
40
|
+
### 4. Redistribution
|
|
41
|
+
|
|
42
|
+
You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
|
|
43
|
+
|
|
44
|
+
a. You must give any other recipients of the Work or Derivative Works a copy of this License; and
|
|
45
|
+
b. You must cause any modified files to carry prominent notices stating that You changed the files; and
|
|
46
|
+
c. You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
|
|
47
|
+
d. If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License.
|
|
48
|
+
|
|
49
|
+
You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
|
|
50
|
+
|
|
51
|
+
### 5. Submission of Contributions
|
|
52
|
+
|
|
53
|
+
Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
|
|
54
|
+
|
|
55
|
+
### 6. Trademarks
|
|
56
|
+
|
|
57
|
+
This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
|
|
58
|
+
|
|
59
|
+
### 7. Disclaimer of Warranty
|
|
60
|
+
|
|
61
|
+
Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
|
|
62
|
+
|
|
63
|
+
### 8. Limitation of Liability
|
|
64
|
+
|
|
65
|
+
In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
|
|
66
|
+
|
|
67
|
+
### 9. Accepting Warranty or Additional Liability
|
|
68
|
+
|
|
69
|
+
While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
|
|
70
|
+
|
|
71
|
+
END OF TERMS AND CONDITIONS
|
|
@@ -0,0 +1,310 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: ttlama-cli
|
|
3
|
+
Version: 0.1.0
|
|
4
|
+
Summary: Interface en ligne de commande pour TTL-LAMa, Time To Live - Lease Access Management
|
|
5
|
+
Author-email: "Rémi Verschuur|rverschuur@audit-io.fr|" <rverschuur@audit-io.fr>
|
|
6
|
+
Maintainer-email: Rémi Verschuur <rverschuur@audit-io.fr>
|
|
7
|
+
License-Expression: Apache-2.0
|
|
8
|
+
Project-URL: Repository, https://github.com/remiv1/TTL-LAMa-CLI
|
|
9
|
+
Keywords: TTL-LAMa,CLI
|
|
10
|
+
Classifier: Development Status :: 4 - Beta
|
|
11
|
+
Classifier: Intended Audience :: Developers
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.12
|
|
13
|
+
Requires-Python: >=3.12
|
|
14
|
+
Description-Content-Type: text/markdown
|
|
15
|
+
License-File: LICENSE
|
|
16
|
+
Requires-Dist: typer<1,>=0.27
|
|
17
|
+
Requires-Dist: platformdirs<5,>=4
|
|
18
|
+
Requires-Dist: requests<3,>=2
|
|
19
|
+
Requires-Dist: keyring<26,>=25
|
|
20
|
+
Requires-Dist: rich<16,>=15
|
|
21
|
+
Requires-Dist: pyyaml<7,>=6
|
|
22
|
+
Provides-Extra: test
|
|
23
|
+
Requires-Dist: pytest<10,>=9; extra == "test"
|
|
24
|
+
Requires-Dist: pytest-cov<8,>=7; extra == "test"
|
|
25
|
+
Provides-Extra: release
|
|
26
|
+
Requires-Dist: build<2,>=1; extra == "release"
|
|
27
|
+
Requires-Dist: twine<8,>=7; extra == "release"
|
|
28
|
+
Dynamic: license-file
|
|
29
|
+
|
|
30
|
+
# TTL-LAMa CLI
|
|
31
|
+
|
|
32
|
+
English | [Français](https://github.com/remiv1/TTL-LAMa-CLI/blob/main/docs/README.fr.md)
|
|
33
|
+
|
|
34
|
+
[](https://www.python.org/)
|
|
35
|
+
[](https://typer.tiangolo.com/)
|
|
36
|
+
[](https://github.com/remiv1/TTL-LAMa-CLI/blob/main/LICENSE)
|
|
37
|
+

|
|
38
|
+
|
|
39
|
+
[](https://github.com/remiv1/TTL-LAMa/blob/main/docs/img/logo_300ppp.png)
|
|
40
|
+
|
|
41
|
+
`ttlama` is the command-line interface for TTL-LAMa (Time-to-Live Lease Administration Manager). It lets users and administrators interact with a TTL-LAMa instance through its HTTP API, without relying on the web interface.
|
|
42
|
+
|
|
43
|
+
The CLI lives in the `cli/` directory and can evolve independently of the server. TTL-LAMa manages temporary network access as leases; the CLI is neither a VPN client nor a general-purpose network administration tool.
|
|
44
|
+
|
|
45
|
+
## Project status
|
|
46
|
+
|
|
47
|
+
The CLI is under development. It provides server configuration, internal and OIDC authentication, self-service and administrative resource management, global configuration operations, and local WireGuard peer commands. The root command also provides `--version` (`-v`).
|
|
48
|
+
|
|
49
|
+
| Group | Available commands | Planned commands |
|
|
50
|
+
| --- | --- | --- |
|
|
51
|
+
| `config` | `set-server` | — |
|
|
52
|
+
| `auth` | `login internal`, `login oidc`, `logout`, `password-chg`, `status` | — |
|
|
53
|
+
| `user` | `get`, `profiles ls`, `profiles get`, `devices ls/get/add/delete`, `leases ls/get/create/revoke` | — |
|
|
54
|
+
| `global-config` | `get`, `diff`, `validate`, `apply` | — |
|
|
55
|
+
| `admin users` | `ls`, `get`, `create`, `update`, `delete`, `assign`, `unassign` | — |
|
|
56
|
+
| `admin devices` | `ls`, `get`, `update`, `block`, `delete` | — |
|
|
57
|
+
| `admin leases` | `ls`, `get`, `revoke` | — |
|
|
58
|
+
| `admin profiles` | `ls`, `get`, `create`, `update`, `delete` | — |
|
|
59
|
+
| `backend wg leases` | `ls`, `get`, `apply`, `delete` | — |
|
|
60
|
+
| `backend openvpn leases` | — | `ls`, `get`, `apply`, `delete` |
|
|
61
|
+
|
|
62
|
+
The `backend wg leases` commands inspect or mutate a local WireGuard interface; they do not provide scheduled reconciliation with the server. See the [command reference](docs/cli-reference.md) for exact arguments and input requirements.
|
|
63
|
+
|
|
64
|
+
Administrators can list leases using any combination of `--user`, `--device`, `--profile`, and `--status` (`active`, `expired`, or `revoked`). `get` displays the complete lease, including its derived status and lifecycle timestamps. `revoke` asks for confirmation before revoking the lease; its history is retained.
|
|
65
|
+
|
|
66
|
+
```bash
|
|
67
|
+
ttlama admin leases ls --status active --yaml
|
|
68
|
+
ttlama admin leases get --lease 73 --json
|
|
69
|
+
ttlama admin leases revoke --lease 73
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Global configuration
|
|
73
|
+
|
|
74
|
+
`ttlama global-config get` reads the server's application YAML document;
|
|
75
|
+
`--json` and `--yaml` emit the raw document structure. Direct secret values are
|
|
76
|
+
shown as `[REDACTED]`. `diff --file` compares a local JSON or YAML candidate
|
|
77
|
+
with the current file, compares redacted secrets on the server, and never prints
|
|
78
|
+
direct secret values; `--check-all` also lists unchanged values.
|
|
79
|
+
`validate --file` asks the server to validate a candidate without writing it.
|
|
80
|
+
`apply --file` displays the changes and asks for confirmation; `--dry-run`
|
|
81
|
+
validates and displays the diff without applying it.
|
|
82
|
+
|
|
83
|
+
This group writes only the application configuration file selected by the
|
|
84
|
+
server's `TTL_LAMA_CONFIG_FILE` setting. It does not manage profile definitions,
|
|
85
|
+
`backend_config.yml`, or profile policies in the database. Replace masked
|
|
86
|
+
secrets with values or secret-file references before applying. Environment
|
|
87
|
+
variables continue to override YAML settings. Applying a file requires an
|
|
88
|
+
external server restart, and the CLI warns when the target is not covered by a
|
|
89
|
+
volume mount because the change may be lost when the container is replaced.
|
|
90
|
+
|
|
91
|
+
```bash
|
|
92
|
+
ttlama global-config get --yaml
|
|
93
|
+
ttlama global-config diff --file config.yml --check-all
|
|
94
|
+
ttlama global-config validate --file config.yml
|
|
95
|
+
ttlama global-config apply --file config.yml --dry-run
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
## Installation and usage
|
|
99
|
+
|
|
100
|
+
The distribution is named `ttlama-cli` and installs the `ttlama` command. The instructions below install the current source checkout in editable mode and do not depend on PyPI. A new release will be published to PyPI in the future.
|
|
101
|
+
|
|
102
|
+
Requirements: Python 3.12 or later and an instance of TTL-LAMa accessible over HTTP(S). From the `cli/` directory, install the package in a virtual environment:
|
|
103
|
+
|
|
104
|
+
```bash
|
|
105
|
+
python -m venv .venv
|
|
106
|
+
source .venv/bin/activate
|
|
107
|
+
python -m pip install -e .
|
|
108
|
+
ttlama --help
|
|
109
|
+
```
|
|
110
|
+
|
|
111
|
+
Configure the instance. The URL includes the scheme and host; provide the port separately:
|
|
112
|
+
|
|
113
|
+
```bash
|
|
114
|
+
ttlama config set-server http://localhost --port 8080
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
Sign in with an internal account. The password is prompted for securely and is not passed as a command argument:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
ttlama auth login internal --user admin
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
The command performs the CSRF exchange required by the API, then stores the access token returned by the server. It does not display the password or token.
|
|
124
|
+
|
|
125
|
+
Sign in with the configured OIDC provider. By default, the CLI opens a browser and listens for a short-lived callback on `127.0.0.1`; `--distant` instead displays a verification URL and user code for approval in another browser. The OIDC client secret stays on the server, and the CLI stores the Bearer token only after successful approval without displaying it.
|
|
126
|
+
|
|
127
|
+
```bash
|
|
128
|
+
ttlama auth login oidc
|
|
129
|
+
ttlama auth login oidc --distant
|
|
130
|
+
```
|
|
131
|
+
|
|
132
|
+
The distant flow requires the provider's discovery document to publish `device_authorization_endpoint` and support the `urn:ietf:params:oauth:grant-type:device_code` grant for the configured client.
|
|
133
|
+
|
|
134
|
+
Change the password of the signed-in account. The current password and the new password are prompted for securely, with a second prompt to confirm the new password. After success, all of the account's sessions are revoked, including the CLI token; sign in again to store a new token.
|
|
135
|
+
|
|
136
|
+
```bash
|
|
137
|
+
ttlama auth password-chg
|
|
138
|
+
```
|
|
139
|
+
|
|
140
|
+
Inspect the current session, including active session expirations, or close the session used by this CLI instance:
|
|
141
|
+
|
|
142
|
+
```bash
|
|
143
|
+
ttlama auth status
|
|
144
|
+
ttlama auth status --json
|
|
145
|
+
ttlama auth status --yaml
|
|
146
|
+
ttlama auth status --check
|
|
147
|
+
ttlama auth logout
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
`status` does not display access tokens or their hashes. With no locally stored token it reports a disconnected state and exits successfully; use `--check` to return a nonzero exit code instead. `logout` revokes only the current CLI session. It removes the local token after success, and also cleans up a token the server reports as invalid; a server/network error keeps the token so the operation can be retried. JSON and YAML status output contain `session` (`active` or `inactive`), `user` (`null` without a local token; otherwise `id`, `username`, `email`, and `is_admin`), and `sessions`, a list of `expires_at` timestamps.
|
|
151
|
+
|
|
152
|
+
## Configuration and credentials
|
|
153
|
+
|
|
154
|
+
The instance address and port are stored in `config.json` under the user configuration directory determined by `platformdirs` (for example, the XDG directory on Linux). The URL must use `http` or `https` and must not contain credentials, query parameters, or a fragment.
|
|
155
|
+
|
|
156
|
+
The access token is stored in the system keyring through `keyring`, in one entry per configured instance. It is not written to the JSON configuration file. A password change revokes this token on the server; the next successful login replaces the local token.
|
|
157
|
+
|
|
158
|
+
## Code layout
|
|
159
|
+
|
|
160
|
+
- `src/ttlama_cli/cli.py` defines the `ttlama` command and its groups.
|
|
161
|
+
- `src/ttlama_cli/commands/` contains the Typer commands, including `auth`, `config`, `global-config`, `admin`, `user`, and `backend`.
|
|
162
|
+
- `src/ttlama_cli/api_client.py` makes HTTP requests to the API.
|
|
163
|
+
- `src/ttlama_cli/config_store.py` validates and persists the configured instance.
|
|
164
|
+
- `src/ttlama_cli/token_store.py` encapsulates access to the system keyring.
|
|
165
|
+
- `tests/` contains the unit and integration tests.
|
|
166
|
+
|
|
167
|
+
## Unit tests
|
|
168
|
+
|
|
169
|
+
Install the test dependencies, then run the test suite from `cli/`:
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
python -m pip install -e '.[test]'
|
|
173
|
+
python -m pytest tests/
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
## Integration tests
|
|
177
|
+
|
|
178
|
+
The launcher starts an ephemeral instance from `ghcr.io/remiv1/ttl-lama:latest`, then runs authentication commands against the real server:
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
./scripts/test-integration.sh
|
|
182
|
+
```
|
|
183
|
+
|
|
184
|
+
The launcher requires Podman Compose and access to the GHCR image. It checks that internal authentication succeeds and an incorrect password is rejected. The test server uses dedicated credentials, the keyring is replaced with in-memory storage, and no host volumes are mounted. The Compose project containers are stopped and removed when the script finishes.
|
|
185
|
+
|
|
186
|
+
## Command tree
|
|
187
|
+
|
|
188
|
+
The current command groups are:
|
|
189
|
+
|
|
190
|
+
```md
|
|
191
|
+
ttlama [--version]
|
|
192
|
+
├── auth → **Authentication** → **_Who am I ?_**
|
|
193
|
+
│ ├── login
|
|
194
|
+
│ │ ├── internal --user <username>
|
|
195
|
+
│ │ └── oidc [--distant | none]
|
|
196
|
+
│ │
|
|
197
|
+
│ ├── logout
|
|
198
|
+
│ ├── password-chg
|
|
199
|
+
│ └── status [--json | --yaml | none] [--check | none]
|
|
200
|
+
│
|
|
201
|
+
├── config
|
|
202
|
+
│ └── set-server <url> [--port <port>]
|
|
203
|
+
│
|
|
204
|
+
├── user → **Utilization** → **_What am I using ?_**
|
|
205
|
+
│ ├── get
|
|
206
|
+
│ │
|
|
207
|
+
│ ├── devices
|
|
208
|
+
│ │ ├── ls
|
|
209
|
+
│ │ ├── get --id <device_id>
|
|
210
|
+
│ │ ├── add --file <file_path>
|
|
211
|
+
│ │ └── delete --id <device_id>
|
|
212
|
+
│ │
|
|
213
|
+
│ ├── leases
|
|
214
|
+
│ │ ├── ls
|
|
215
|
+
│ │ ├── get --id <lease_id>
|
|
216
|
+
│ │ ├── create --file <file_path>
|
|
217
|
+
│ │ └── revoke --id <lease_id>
|
|
218
|
+
│ │
|
|
219
|
+
│ └── profiles
|
|
220
|
+
│ ├── ls
|
|
221
|
+
│ └── get --id <profile_id>
|
|
222
|
+
│
|
|
223
|
+
├── global-config → **Configuration** → **_How does the instance work ?_**
|
|
224
|
+
│ ├── get [--json | none] [--yaml | none]
|
|
225
|
+
│ ├── diff --file <file_path> [--check-all | none]
|
|
226
|
+
│ ├── validate --file <file_path>
|
|
227
|
+
│ └── apply --file <file_path> [--dry-run | none]
|
|
228
|
+
│
|
|
229
|
+
├── admin → **Administration** → **_Who has what rights / What is the administered state ?_**
|
|
230
|
+
│ │
|
|
231
|
+
│ ├── users
|
|
232
|
+
│ │ ├── ls [--device <id> | none ] [--lease <id> | none ] [--profile <id> | none]
|
|
233
|
+
│ │ ├── get <user_id>
|
|
234
|
+
│ │ ├── create --file <file_path>
|
|
235
|
+
│ │ ├── update --user <user_id> --file <file_path>
|
|
236
|
+
│ │ ├── delete --user <user_id>
|
|
237
|
+
│ │ ├── assign --user <user_id> --profile <profile_id>
|
|
238
|
+
│ │ └── unassign --user <user_id> --profile <profile_id>
|
|
239
|
+
│ │
|
|
240
|
+
│ ├── devices
|
|
241
|
+
│ │ ├── ls [--lease <id> | none ] [--profile <id> | none]
|
|
242
|
+
│ │ ├── get --device <device_id>
|
|
243
|
+
│ │ ├── update --device <device_id> --file <file_path>
|
|
244
|
+
│ │ ├── block --device <device_id>
|
|
245
|
+
│ │ └── delete --device <device_id>
|
|
246
|
+
│ │
|
|
247
|
+
│ ├── leases
|
|
248
|
+
│ │ ├── ls [--user <id> | none ] [--device <id> | none ] [--profile <id> | none ] [--status <status> | none]
|
|
249
|
+
│ │ ├── get --lease <lease_id>
|
|
250
|
+
│ │ └── revoke --lease <lease_id>
|
|
251
|
+
│ │
|
|
252
|
+
│ └── profiles
|
|
253
|
+
│ ├── ls [--user <id>] [--device <id>] [--lease <id>]
|
|
254
|
+
│ ├── get --profile <profile_id> [--json | --yaml | none]
|
|
255
|
+
│ ├── create --file <file_path>
|
|
256
|
+
│ ├── update --profile <profile_id> --file <file_path>
|
|
257
|
+
│ └── delete --profile <profile_id>
|
|
258
|
+
│
|
|
259
|
+
└── backend → **Local VPN backend operations**
|
|
260
|
+
│
|
|
261
|
+
├── wg
|
|
262
|
+
│ └── leases
|
|
263
|
+
│ ├── ls [--device <id> | none ]
|
|
264
|
+
│ ├── get --lease <lease_id>
|
|
265
|
+
│ ├── apply --file <file_path>
|
|
266
|
+
│ └── delete --lease <lease_id>
|
|
267
|
+
│
|
|
268
|
+
├── openvpn
|
|
269
|
+
│ └── ...
|
|
270
|
+
│
|
|
271
|
+
└── ...
|
|
272
|
+
```
|
|
273
|
+
|
|
274
|
+
The root command also supports `--install-completion` and `--show-completion`. Retrieve the complete CLI command documentation in [cli-reference.md](docs/cli-reference.md).
|
|
275
|
+
|
|
276
|
+
### Input file examples
|
|
277
|
+
|
|
278
|
+
Ready-to-use JSON and YAML examples for every `--file` command are available in [docs/examples/](https://github.com/remiv1/TTL-LAMa-CLI/blob/main/docs/examples/): users (`users/user-create`, `users/user-update`), profiles (`profiles/profile-create`, `profiles/profile-update`), devices (`devices/device-add`, `devices/device-update`), and leases (`leases/lease-create`).
|
|
279
|
+
|
|
280
|
+
### Admin user files
|
|
281
|
+
|
|
282
|
+
`ttlama admin users create --file` and `update --user <user_id> --file` accept UTF-8 JSON or YAML objects. Create files require `username`; `email`, `enabled`, `is_admin`, and `password` are optional. Update files contain only the fields to change; use `email: null` to clear the email address. A password in the input file is sent to the API but is never displayed by the CLI. If no password is supplied and the server uses internal authentication, the API generates one and the CLI displays it in the creation response only; save it immediately because it cannot be retrieved later. Without internal authentication, no internal credential is created when the password is omitted.
|
|
283
|
+
|
|
284
|
+
Create files may also include `oidc_links`, a list of identities identified by `issuer` and `subject`. Update files use `link_oidc` to add identities and `unlink_oidc` to remove them. Both values must exactly match the issuer and `sub` supplied by the OIDC provider; identities are not matched by email. An identity already linked to another account causes a conflict. Repeating a link or unlink operation has no additional effect. The CLI warns when unlinking because removing the last identity prevents future OIDC sign-in for that account.
|
|
285
|
+
|
|
286
|
+
The JSON or YAML output of `ttlama admin users get <user_id> --json` or `--yaml` is a flat object containing the editable fields returned by the API and can be passed directly to `update --user <user_id> --file`. List output remains a collection and is not an update body. Passwords are never returned; add a `password` field manually when changing one.
|
|
287
|
+
|
|
288
|
+
`ttlama admin users assign --user <user_id> --profile <profile_id>` assigns a
|
|
289
|
+
profile to a user; repeating the command is idempotent. The matching
|
|
290
|
+
`unassign` command revokes the active assignment and its associated leases.
|
|
291
|
+
|
|
292
|
+
### Admin device files
|
|
293
|
+
|
|
294
|
+
`ttlama admin devices update --device <device_id> --file` accepts a UTF-8 JSON or YAML object with one or both of `name` and `public_key`. Device ownership and lifecycle fields cannot be changed. The JSON or YAML output of `ttlama admin devices get --device <device_id> --json` or `--yaml` contains only those editable fields and can be passed directly to `update --file`. The default console view shows the complete device record; the list table omits public keys, while structured list output contains the full API records. The `ls` filters `--lease` and `--profile` can be combined.
|
|
295
|
+
|
|
296
|
+
Both `block` and `delete` ask for confirmation and revoke the device's active leases. `block` marks the device as blocked; `delete` is a logical deletion that retains the device history.
|
|
297
|
+
|
|
298
|
+
### Admin profile files
|
|
299
|
+
|
|
300
|
+
`ttlama admin profiles create --file` accepts a UTF-8 JSON or YAML object with `name`, `default_duration`, `maximum_duration`, and a non-empty `networks` list of CIDRs. Durations use `d`, `h`, `m`, or `s` units, and the default cannot exceed the maximum. For example:
|
|
301
|
+
|
|
302
|
+
```yaml
|
|
303
|
+
name: office-access
|
|
304
|
+
default_duration: 1h
|
|
305
|
+
maximum_duration: 8h
|
|
306
|
+
networks:
|
|
307
|
+
- 10.0.0.0/24
|
|
308
|
+
```
|
|
309
|
+
|
|
310
|
+
`update --profile <profile_id> --file` accepts any subset of those fields. `get --profile <profile_id> --json` and `--yaml` output a flat object that can be passed to `update --file`; `ls` filters `--user`, `--device`, and `--lease` are combined with AND. Historical profiles without a policy return only their name, so add the complete policy fields before updating one. Deleting a profile requires typing its full name, then revokes it and its dependent assignments and leases.
|