Compare commits

...

1 Commits

Author SHA1 Message Date
cfc015c42e update secret generation docs 2026-02-15 20:56:03 +01:00

View File

@ -582,23 +582,6 @@ Add the `# generate=false` comment
SECRET_JWT_SECRET_VERSION=v1 # generate=false SECRET_JWT_SECRET_VERSION=v1 # generate=false
``` ```
## How do I specify the charset for a specific secret generation
!!! warning "Watch out for old versions of `abra` 🚧"
This feature is only available in the >= 0.10.x series of `abra`.
```
SECRET_JWT_SECRET_VERSION=v1 # charset=default,special
```
Options are:
* `special`: [source](https://github.com/decentral1se/passgen/blob/8404cb922dea92efa8c3514f0ec8c37ce12a880f/const.go#L22C29-L22C43)
* `safespecial`: [source](https://git.coopcloud.tech/toolshed/abra/src/commit/6abaf7a094df1a96599af2c4cbae1769821ad17c/pkg/secret/secret.go#L182)
* `default,special`: mix of `default` and `special`
* `default,safespecial`: mix of `default` and `safespecial`
## How do I change secret generation length? ## How do I change secret generation length?
It is possible to tell `abra` which length it should generate secrets with from your recipe config. It is possible to tell `abra` which length it should generate secrets with from your recipe config.
@ -620,6 +603,13 @@ of passwords which admins have to type out in database shells.
## How do I change secret generation characters? ## How do I change secret generation characters?
!!! warning "Watch out for old versions of `abra` 🚧"
This feature is only available in the >= 0.10.x series of `abra`.
The generation of `hex` secrets is only available in the >= 0.12.x series of `abra`.
The generation of `bytes` secrets is only available in the >= 0.13.x series of `abra`.
It is also possible to tell `abra` which characters it should use to generate secrets with from your recipe config. It is also possible to tell `abra` which characters it should use to generate secrets with from your recipe config.
You do this by adding an additional modifier in the inline comment on the secret definition in the `.env.sample` / `.env` file. You do this by adding an additional modifier in the inline comment on the secret definition in the `.env.sample` / `.env` file.
@ -640,10 +630,52 @@ The possible Values are:
| `default,special` | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789!@#$%^&*_-+=` | Uses uppercase letters, lowercase letters and numbers and special characters | | `default,special` | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789!@#$%^&*_-+=` | Uses uppercase letters, lowercase letters and numbers and special characters |
| `default,safespecial` | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789!@#%^&*_-+=` | Uses uppercase letters, lowercase letters and numbers and console safe special characters | | `default,safespecial` | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789!@#%^&*_-+=` | Uses uppercase letters, lowercase letters and numbers and console safe special characters |
| `default` | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789` | Uses uppercase letters, lowercase letters and numbers | | `default` | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789` | Uses uppercase letters, lowercase letters and numbers |
| `hex` | `0123456789abcdef` | Uses only hexadecimal characters (0-9, a-f) |
| `bytes` | N/A (generates random bytes) | Generates random bytes instead of character-based passwords (requires `length` modifier, automatically uses `encoding=base64`) |
| any other value or not setting one will be treated as `default` | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789` | Uses uppercase letters, lowercase letters and numbers | | any other value or not setting one will be treated as `default` | `abcdefghijkmnopqrstuvwxyzABCDEFGHJKLMNPQRSTUVWXYZ23456789` | Uses uppercase letters, lowercase letters and numbers |
The setting does only apply when you also set a length modifier to the secret (documented [here](/maintainers/handbook/#how-do-i-change-secret-generation-length)), so it is not applicable for the "easy to remember word" style generator that used when you don't set a length. The setting does only apply when you also set a length modifier to the secret (documented [here](/maintainers/handbook/#how-do-i-change-secret-generation-length)), so it is not applicable for the "easy to remember word" style generator that used when you don't set a length.
## How do I encode generated secrets?
!!! warning "Watch out for old versions of `abra` 🚧"
This feature is only available in the >= 0.13.x series of `abra`.
You can tell `abra` to encode generated secrets using the `encoding` modifier in the inline comment on the secret definition in the `.env.sample` / `.env` file.
Here is an example:
```bash
SECRET_API_KEY_VERSION=v1 # length=32 encoding=base64
```
This will generate a 32-character secret and then base64-encode it before storing.
Currently supported encoding options:
- `base64`: Base64-encodes the generated secret value
**Note:** When using `charset=bytes`, the encoding automatically defaults to `base64` even if not explicitly specified, as raw binary data needs to be encoded for safe storage.
## How do I add a prefix to generated secrets?
!!! warning "Watch out for old versions of `abra` 🚧"
This feature is only available in the >= 0.13.x series of `abra`.
You can tell `abra` to add a prefix to generated secrets using the `prefix` modifier in the inline comment on the secret definition in the `.env.sample` / `.env` file.
Here is an example:
```bash
SECRET_APP_KEY_VERSION=v1 # length=32 charset=bytes prefix=base64:
```
This will generate a 32-byte random key, base64-encode it, and prefix it with `base64:`. This is useful for applications like Laravel that expect secrets in a specific format.
The prefix is applied after any encoding transformations.
## How do I configure backup/restore? ## How do I configure backup/restore?
From the perspective of the recipe maintainer, backup/restore is just more From the perspective of the recipe maintainer, backup/restore is just more