Nasqueron Agora - User contributions [en]

Keruald

2026-04-19T10:15:01Z

Dereckson: /* Troubleshoot */ +arc unit

'''Keruald''' is a set of libraries to build PHP applications.

== Libraries ==

{| class="wikitable"
|+ List of libraries
|-
! Package name !! Description
|-
| keruald/omnitools || General purpose library
|-
| keruald/globalfunctions || Wrapper to replace our old old sites "core.php" by calls to omnitools
|-
| keruald/commands || Create simple CLI application
|-
| keruald/report || Reporting library
|-
| keruald/health || Site health check
|-
| keruald/dockerhub || Docker Hub, managing payload signatures
|-
| keruald/github || GitHub payloads for webhooks - managing payload signatures, class representations
|-
| keruald/mailgun || Mailgun API client
|-
| keruald/database || Database abstraction layer
|-
| keruald/broker || Wrapper around brokers like RabbitMQ
|}

== Developer guide ==
=== Contribution workflow ===

You'll find the general contribution guide at [[How to contribute code]]. Here some pointers specific for Keruald libraries.

We use a '''monorepo''': clone the rKERUALD repository on DevCentral, you'll find your library as a direct subdirectory on it.

Each subdirectory matches:
* a resource folder, not included in packages, if starting by an underscore _ or a dot .
* a name of a package if starting by a letter, e.g. keruald/commands for commands/

==== New version of a library ====

''This should be automated through Jenkins.''

To publish a new version of a library:
* Create a new tag using library/version format, e.g. foo/1.2.3
* Run <code>./_utils/repo/export-commits-to-manyrepo.sh foo</code>
* Tag with versions the new commits in the library repository (tags propagation isn't currently automated)
** compare <code>git log</code> from monorepo and library repo
** Add tag without any prefix in library repo, e.g. <code>git tag 1.2.3</code>

=== How to import an existing library? ===

First, use [https://github.com/hraban/tomono tomono] in the PARENT DIRECTORY of the monorepo directory.

If the name of the repository is NOT "core", export it as MONOREPO_NAME environment variable.

For example, to import Keruald/GitHub library:

<syntaxhighlight lang="console">
$ export MONOREPO_NAME=keruald
$ echo "ssh://vcs@devcentral.nasqueron.org:5022/source/github.git github" | tomono --continue
From ssh://devcentral.nasqueron.org:5022/source/github
* [new branch] main -> github/main
* [new tag] 0.1.0 -> github/0.1.0
* [new tag] 0.1.1 -> github/0.1.1
* [new tag] 0.2.0 -> github/0.2.0
* [new tag] 0.2.1 -> github/0.2.1
Updated 6 paths from the index
</syntaxhighlight>

Then follow the procedure for a new library to update the monorepo metadata.

Don't forget to use <code>composer dump-autoload</code> to update your local Composer autoloader.

=== How to create a new library? ===
To create a new library quux, we need a new empty manyrepo on DevCentral, a mirror on GitHub and to declare it on Packagist:

# Declare your library in <code>metadata.yml</code>
# Regenerate shared files with <code>make regenerate</code> (you need Python and Jinja2): that will add your repository to files like phpcs.xml
# Create on DevCentral a new repository with a callsign starting by K for Keruald like KQUUX, and "quux" as shortname
# Create on GitHub a new repository called keruald/quux
# Publish on packagist

If the shortname is already taken on DevCentral, it's time to create a new task to provide a map of subdirectory/package repository.

Don't commit anything in newly created repos but contribute as usual by creating quux/ subdirectory in the monorepo

=== Troubleshoot ===
==== Run Arcanist unit tests ====
Before running an arc unit or arc diff command, you need to set the XDEBUG_MODE environment variable to "coverage".

This is done automatically by the Arcanist code installed on devserver role. For local development, use arcanist with the patches from our production branch. It's available at https://github.com/nasqueron/arcanist

==== Error: Class "Keruald\GitHub\XHubSignature" not found ====
When a new library is added to the repository, a new entry is added to composer.json to provide that library.

The Composer autoloader needs then to be updated with <code>composer dump-autoload</code>.

=== Annex A. IDE configuration ===
==== PhpStorm ====

Clone the monorepo on your drive, then open it in PhpStorm to generate an .idea folder.

* Edit keruald.iml with this modules content to declare the code namespaces: https://devcentral.nasqueron.org/P300
* For code style, you can use https://github.com/nasqueron/codestyle/blob/main/JetBrains/php-codestyle.xml

User:Dereckson/Devserver

2026-04-13T12:44:02Z

Dereckson: Log is available per D4057

== MediaWiki ==
=== Logs ===
tail -n 100 -f /var/log/www/dereckson.be/mediawiki-php.log

=== Reinstall ===
* /var/51-wwwroot/mediawiki-dereckson/core: wikimedia/core repository
* /var/51-wwwroot/mediawiki-dereckson/core/extensions: symlink to <code>../extensions</code>
** Clone all needed extensions in /var/51-wwwroot/mediawiki-dereckson/extensions
* /var/51-wwwroot/mediawiki-dereckson/core/skins: symlink to <code>../skins</code>
** Same with git clone ssh://review/mediawiki/skins/
* /var/dataroot/mediawiki.dereckson.be/data contains:
** my_wiki.sqlite for the content
** wikicache.sqlite for the cache

=== Update ===
* '''Core:''' mw-update-core (currently writing it)

=== Create a new extension ===
;I. Wikimedia side
* [[mw:Manual:Developing_extensions]]
* [[mw:Gerrit/New repositories/Requests]]
* [https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?projects=Project-Admins Create task for new Phabricator project]

;II. WindRiver

<syntaxhighlight lang="shell">
$ setenv MW_EXTENSION foo
$ cd ~/dev/wikimedia/mediawiki/extensions
$ git clone ssh://review/mediawiki/extensions/$MW_EXTENSION || git init $MW_EXTENSION
</syntaxhighlight>

Extension is actually stored at /var/51-wwwroot/mediawiki-dereckson/extensions, so can immediately be configured to test locally.

;III. SaaS deployment
* {{Ops file|pillar/saas/mediawiki.sls}}
* [https://devcentral.nasqueron.org/source/saas-mediawiki/browse/main/config/Settings.php config/Settings.php]

=== Troubleshoot ===
==== SQLite database is read-only ====
Runtime error near line 2: attempt to write a readonly database (8)

<syntaxhighlight lang="shell">
chown -R web-be-dereckson-mw:dereckson /var/dataroot/mediawiki.dereckson.be/data
chmod 771 /var/dataroot/mediawiki.dereckson.be/data
chmod 660 /var/dataroot/mediawiki.dereckson.be/data/my_wiki.sqlite
</syntaxhighlight>

=== Permissions to run tests and maintenance scripts ===
To run tests against wiki and maintenance scripts as user can be tricky:

<syntaxhighlight lang="shell">
touch /tmp/mw-GlobalIdGenerator5001-UID-nodeid /tmp/mw-GlobalIdGenerator5001-UUID-128
chown web-be-dereckson-mw:dereckson /tmp/mw-GlobalIdGenerator5001-*
chmod 664 /tmp/mw-GlobalIdGenerator5001-*

chmod 771 /var/dataroot/mediawiki.dereckson.be/data/locks
</syntaxhighlight>

== Zed ==
=== Useful paths ===
{| class="wikitable"
|+ Paths for Zed development
|-
! File path !! Managed by !! Notes
|-
| /usr/local/etc/nginx/vhosts/dereckson.be/zed51.conf || Salt :: webserver-alkane
|-
| /var/51-wwwroot/zed/ || Salt :: wwwroot-51 (still to do) || Git repo: git@github.com:dereckson/zed.git
|-
| /var/dataroot/zed/content/ || Manually || Git repo: git@github.com:hypership/content.git
|}

=== Logs ===
* nginx: <code>tail -n 100 -f /var/log/www/dereckson.be/zed51-error.log</code>
* PHP: <code>tail -n 100 -f /var/log/www/dereckson.be/zed51-php.log</code>

=== Staging ===

'''Note. Keruald is currently symlinked from the monorepo to vendor/keruald.'''

To recreate Zed staging area:

$ cd /var/dataroot/zed/content
$ git init .
$ git config --global --add safe.directory /var/dataroot/zed/content
$ git remote add origin git@github.com:hypership/content.git
$ git fetch --all
$ git reset --hard origin/main
$ git clone git@github.com:hypership/content_users.git users

$ sudo -u web-be-dereckson-zed51 mkdir /var/dataroot/zed/cache/sessions
$ sudo mkdir -p /var/dataroot/zed/content/users/_photos/tn
$ sudo chown -R web-be-dereckson-zed51:dereckson /var/dataroot/zed/content/users/_photos
$ sudo chmod 771 /var/dataroot/zed/content/users/_photos /var/dataroot/zed/content/users/_photos/tn

$ mkdir -p /home/dereckson/dev/zed/hypership
$ cd /home/dereckson/dev/zed/hypership
$ ln -s /var/dataroot/zed/content

Note: Zed currently not defined in wwwroot-51 in rOPS, should be done for /var/51-wwwroot/zed

== IRC ==

=== Troubleshoot ===
==== Error loading module proxy/irc ====
When trying to load proxy module, I got:

22:00:09 -!- Irssi: Error loading module proxy/irc: /home/dereckson/.irssi/modules/libirc_proxy.so: Undefined symbol "g_input_add"

Proxy is now compiled by default, personal module needs to be deleted.

User:Dereckson/Devserver

2026-04-13T12:19:27Z

Dereckson: /* Zed */

== MediaWiki ==
=== Logs ===
tail -n 100 -f /var/log/www/dereckson.be/mediawiki-php.log

=== Reinstall ===
* /var/51-wwwroot/mediawiki-dereckson/core: wikimedia/core repository
* /var/51-wwwroot/mediawiki-dereckson/core/extensions: symlink to <code>../extensions</code>
** Clone all needed extensions in /var/51-wwwroot/mediawiki-dereckson/extensions
* /var/51-wwwroot/mediawiki-dereckson/core/skins: symlink to <code>../skins</code>
** Same with git clone ssh://review/mediawiki/skins/
* /var/dataroot/mediawiki.dereckson.be/data contains:
** my_wiki.sqlite for the content
** wikicache.sqlite for the cache

=== Update ===
* '''Core:''' mw-update-core (currently writing it)

=== Create a new extension ===
;I. Wikimedia side
* [[mw:Manual:Developing_extensions]]
* [[mw:Gerrit/New repositories/Requests]]
* [https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?projects=Project-Admins Create task for new Phabricator project]

;II. WindRiver

<syntaxhighlight lang="shell">
$ setenv MW_EXTENSION foo
$ cd ~/dev/wikimedia/mediawiki/extensions
$ git clone ssh://review/mediawiki/extensions/$MW_EXTENSION || git init $MW_EXTENSION
</syntaxhighlight>

Extension is actually stored at /var/51-wwwroot/mediawiki-dereckson/extensions, so can immediately be configured to test locally.

;III. SaaS deployment
* {{Ops file|pillar/saas/mediawiki.sls}}
* [https://devcentral.nasqueron.org/source/saas-mediawiki/browse/main/config/Settings.php config/Settings.php]

=== Troubleshoot ===
==== SQLite database is read-only ====
Runtime error near line 2: attempt to write a readonly database (8)

<syntaxhighlight lang="shell">
chown -R web-be-dereckson-mw:dereckson /var/dataroot/mediawiki.dereckson.be/data
chmod 771 /var/dataroot/mediawiki.dereckson.be/data
chmod 660 /var/dataroot/mediawiki.dereckson.be/data/my_wiki.sqlite
</syntaxhighlight>

=== Permissions to run tests and maintenance scripts ===
To run tests against wiki and maintenance scripts as user can be tricky:

<syntaxhighlight lang="shell">
touch /tmp/mw-GlobalIdGenerator5001-UID-nodeid /tmp/mw-GlobalIdGenerator5001-UUID-128
chown web-be-dereckson-mw:dereckson /tmp/mw-GlobalIdGenerator5001-*
chmod 664 /tmp/mw-GlobalIdGenerator5001-*

chmod 771 /var/dataroot/mediawiki.dereckson.be/data/locks
</syntaxhighlight>

== Zed ==
=== Useful paths ===
{| class="wikitable"
|+ Paths for Zed development
|-
! File path !! Managed by !! Notes
|-
| /usr/local/etc/nginx/vhosts/dereckson.be/zed51.conf || Salt :: webserver-alkane
|-
| /var/51-wwwroot/zed/ || Salt :: wwwroot-51 (still to do) || Git repo: git@github.com:dereckson/zed.git
|-
| /var/dataroot/zed/content/ || Manually || Git repo: git@github.com:hypership/content.git
|}

=== Logs ===
* nginx: <code>tail -n 100 -f $LOG</code> - still to provision, currently general one
* PHP: <code>tail -n 100 -f /var/log/www/dereckson.be/zed51-php.log</code>

=== Staging ===

'''Note. Keruald is currently symlinked from the monorepo to vendor/keruald.'''

To recreate Zed staging area:

$ cd /var/dataroot/zed/content
$ git init .
$ git config --global --add safe.directory /var/dataroot/zed/content
$ git remote add origin git@github.com:hypership/content.git
$ git fetch --all
$ git reset --hard origin/main
$ git clone git@github.com:hypership/content_users.git users

$ sudo -u web-be-dereckson-zed51 mkdir /var/dataroot/zed/cache/sessions
$ sudo mkdir -p /var/dataroot/zed/content/users/_photos/tn
$ sudo chown -R web-be-dereckson-zed51:dereckson /var/dataroot/zed/content/users/_photos
$ sudo chmod 771 /var/dataroot/zed/content/users/_photos /var/dataroot/zed/content/users/_photos/tn

$ mkdir -p /home/dereckson/dev/zed/hypership
$ cd /home/dereckson/dev/zed/hypership
$ ln -s /var/dataroot/zed/content

Note: Zed currently not defined in wwwroot-51 in rOPS, should be done for /var/51-wwwroot/zed

== IRC ==

=== Troubleshoot ===
==== Error loading module proxy/irc ====
When trying to load proxy module, I got:

22:00:09 -!- Irssi: Error loading module proxy/irc: /home/dereckson/.irssi/modules/libirc_proxy.so: Undefined symbol "g_input_add"

Proxy is now compiled by default, personal module needs to be deleted.

Module:ProjectBox

2026-04-09T17:52:40Z

Dereckson:

-- Module:ProjectInfobox
-- Renders a structured infobox for a project page.
-- Usage: {{#invoke:ProjectInfobox|render}}

local p = {}

-- Split a comma-separated string into a trimmed list.
local function splitList(value)
local items = {}
for item in value:gmatch("[^,]+") do
table.insert(items, mw.text.trim(item))
end
return items
end

-- Wrap a value in a table cell pair (label / value).
local function row(label, value)
return mw.html.create("tr")
:tag("th"):addClass("project-infobox__label"):wikitext(label):done()
:tag("td"):addClass("project-infobox__value"):wikitext(value):done()
end

-- Render participants as a comma-separated inline list.
local function participantCell(raw)
local names = splitList(raw)
local linked = {}
for _, name in ipairs(names) do
table.insert(linked, "[[User:" .. name .. "|" .. name .. "]]")
end
return table.concat(linked, ", ")
end

function p.render(frame)
local args = frame:getParent().args

local group = mw.text.trim(args.group or "")
local project = mw.text.trim(args.project or "")
local participants = mw.text.trim(args.participants or "")
local status = mw.text.trim(args.status or "")
local description = mw.text.trim(args.description or "")

local root = mw.html.create("table"):addClass("project-infobox")
local tbody = root:tag("tbody")

-- Header row: project name as caption
root:tag("caption")
:addClass("project-infobox__title")
:wikitext(project ~= "" and project or "Project")

if group ~= "" then
tbody:node(row("Group", group))
end

if project ~= "" then
tbody:node(row("Project", project))
end

if status ~= "" then
tbody:node(row("Status", status))
end

if participants ~= "" then
tbody:node(row("Participants", participantCell(participants)))
end

if description ~= "" then
tbody:tag("tr")
:tag("td")
:attr("colspan", "2")
:addClass("project-infobox__description")
:wikitext(description)
end

return tostring(root)
end

return p

Module:ProjectBox

2026-04-09T17:41:03Z

Dereckson:

local p = {}

local function renderRow(label, value)
if not value or value == "" then
return ""
end
return string.format(
'<tr><th>%s</th><td>%s</td></tr>',
label, value
)
end

function p.render(frame)
local args = frame:getParent().args

local html = {}

table.insert(html, '<table class="infobox project-infobox">')

-- Title
if args.project and args.project ~= "" then
table.insert(html,
string.format('<tr><th colspan="2" class="infobox-title">%s</th></tr>', args.project)
)
end

-- Rows
table.insert(html, renderRow("Group", args.group))
table.insert(html, renderRow("Participants", args.participants))

table.insert(html, '</table>')

return table.concat(html, '\n')
end

return p

Module:ProjectBox

2026-04-09T17:38:42Z

Dereckson: Created page with "local p = {} local function renderRow(label, value) if not value or value == "" then return "" end return string.format( '<tr><th>%s</th><td>%s</td></tr>', label, value ) end function p.render(frame) local args = frame:getParent().args local html = {} table.insert(html, '{| class="infobox project-infobox"') -- Title (project name) if args.project then table.insert(html, string.format('! colspan="2" c..."

local p = {}

local function renderRow(label, value)
if not value or value == "" then
return ""
end
return string.format(
'<tr><th>%s</th><td>%s</td></tr>',
label, value
)
end

function p.render(frame)
local args = frame:getParent().args

local html = {}
table.insert(html, '{| class="infobox project-infobox"')

-- Title (project name)
if args.project then
table.insert(html, string.format('! colspan="2" class="infobox-title" | %s', args.project))
end

table.insert(html, '|-')

-- Rows
table.insert(html, renderRow("Group", args.group))
table.insert(html, renderRow("Participants", args.participants))

table.insert(html, '|}')

return table.concat(html, '\n')
end

return p

User:Dereckson/Sandbox

2026-04-09T17:37:22Z

Dereckson:

{{#invoke:ProjectBox|render
| project = Some project
| group = Nasqueron Operations SIG
| participants = Dereckson ⬪ ptdradmin
}}

User:Dereckson/Sandbox

2026-04-09T17:37:10Z

Dereckson: Created page with "{{#invoke:ProjectInfobox|render | project = Some project | group = Nasqueron Operations SIG | participants = Dereckson ⬪ ptdradmin }}"

{{#invoke:ProjectInfobox|render
| project = Some project
| group = Nasqueron Operations SIG
| participants = Dereckson ⬪ ptdradmin
}}

Operations grimoire/Anubis

2026-04-09T17:30:58Z

Dereckson:

'''Anubis''' is a proxy to filter out AI scrapers requests. It will allow sites like [[Operations grimoire/DevCentral|DevCentral]] to stop to serve heavy traffic for LLM model training.

__TOC__

== Challenges ==
We want to stop scraping traffic, but let legitimate traffic pass (e.g. CLI requests from Conduit).

Anubis is used by a lot of similar software forges from open-source projects: [https://anubis.techaro.lol/docs/user/known-instances Anubis known instances], but it's unclear if someone already succeed to configure it for Phabricator.

It's our current field of investigation by Gui and Dereckson.

At Wikimedia, Andrew Kostka (WMDE) has some experience deploying it, apparently for Wikibase products.

== Implementation (by Gui) ==
=== Isolation via UNIX Sockets ===
To avoid to maintain a table of TCP ports, each instance is configured to use UNIX sockets for both traffic and metrics:
* '''Main socket:''' <code><nowiki>/run/anubis/{{ instance }}.sock</nowiki></code>
* '''Metrics socket:''' <code><nowiki>/run/anubis/{{ instance }}-metrics.sock</nowiki></code>

=== Dynamic Configuration ===
The Salt states resolve the target application's port from the `docker_containers` pillar. In `anubis_instances`, we define the target:
<pre>
anubis_instances:
devcentral:
target:
service: phabricator
container: devcentral
</pre>

=== Provisioning and Vault ===
Anubis API and Dashboard keys are provisioned in '''Vault''' using a helper script [scripts/fix_anubis_devcentral.sh](cci:7://file:///C:/Users/Gui%20Martinien/Downloads/operations-main/operations-main/scripts/fix_anubis_devcentral.sh:0:0-0:0) and retrieved by Salt during deployment.

== Current work ==
* Gui deployed an experimental run manually on Dwellers to figure how we can build and configure Anubis
* Work to deploy Anubis with Salt: [https://devcentral.nasqueron.org/D3908 D3908]

== Troubleshoot ==
=== Each site must have its own Anubis instance ===
If you serve to protect two different domains, you need two Anubis instances, one per domain.

In December, we noticed strange errors about challenges not found trying to fire the same instance for two different targets from the same domain.

== See also ==
* [https://anubis.techaro.lol/ Anubis website]

Operations grimoire/Anubis

2026-04-09T17:30:21Z

Dereckson: /* Isolation via UNIX Sockets */

'''Anubis''' is a proxy to filter out AI scrapers requests. It will allow sites like [[Operations grimoire/DevCentral|DevCentral]] to stop to serve heavy traffic for LLM model training.

__TOC__

== Challenges ==
We want to stop scraping traffic, but let legitimate traffic pass (e.g. CLI requests from Conduit).

Anubis is used by a lot of similar software forges from open-source projects: [https://anubis.techaro.lol/docs/user/known-instances Anubis known instances], but it's unclear if someone already succeed to configure it for Phabricator.

It's our current field of investigation by Doba Gui and Dereckson.

At Wikimedia, Andrew Kostka (WMDE) has some experience deploying it, apparently for Wikibase products.

== Implementation (by Doba Gui) ==
=== Isolation via UNIX Sockets ===
To avoid to maintain a table of TCP ports, each instance is configured to use UNIX sockets for both traffic and metrics:
* '''Main socket:''' <code><nowiki>/run/anubis/{{ instance }}.sock</nowiki></code>
* '''Metrics socket:''' <code><nowiki>/run/anubis/{{ instance }}-metrics.sock</nowiki></code>

=== Dynamic Configuration ===
The Salt states resolve the target application's port from the `docker_containers` pillar. In `anubis_instances`, we define the target:
<pre>
anubis_instances:
devcentral:
target:
service: phabricator
container: devcentral
</pre>

=== Provisioning and Vault ===
Anubis API and Dashboard keys are provisioned in '''Vault''' using a helper script [scripts/fix_anubis_devcentral.sh](cci:7://file:///C:/Users/Gui%20Martinien/Downloads/operations-main/operations-main/scripts/fix_anubis_devcentral.sh:0:0-0:0) and retrieved by Salt during deployment.

== Current work ==
* Doba deployed an experimental run manually on Dwellers to figure how we can build and configure Anubis
* Work to deploy Anubis with Salt: [https://devcentral.nasqueron.org/D3908 D3908]

== Troubleshoot ==
=== Each site must have its own Anubis instance ===
If you serve to protect two different domains, you need two Anubis instances, one per domain.

In December, we noticed strange errors about challenges not found trying to fire the same instance for two different targets from the same domain.

== See also ==
* [https://anubis.techaro.lol/ Anubis website]

Operations grimoire/Configuration files

2026-04-05T21:07:45Z

Dereckson: Draft

This page lists configuration files managed by our SaltStack operations repository (rOPS).

Each file is deployed from {{Ops file|roles/}} subfolders. The '''Full path''' column shows the path relative to {{Ops file|roles/}}.

== bastion ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| sshd-otp || SSH || {{Ops file|roles/bastion/sshd-otp/files/sshd.rc}} || [https://docs.freebsd.org/en/articles/rc-scripting/ RC scripting]
|-
| sshd-otp || SSH || {{Ops file|roles/bastion/sshd-otp/files/sshd.rc.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| sshd-otp || systemd || {{Ops file|roles/bastion/sshd-otp/files/sshd.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|}

== core ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| certificates || syslog || {{Ops file|roles/core/certificates/files/acmesh/syslog.conf}} || [https://www.rsyslog.com/doc/ rsyslog documentation]
|-
| certificates || Certbot || {{Ops file|roles/core/certificates/files/certbot/cli.ini}} || [https://eff-certbot.readthedocs.io/en/latest/ Certbot documentation]
|-
| login || BSD login || {{Ops file|roles/core/login/files/login.conf}} || [https://man.freebsd.org/cgi/man.cgi?login.conf login.conf man page]
|-
| monitoring || Prometheus || {{Ops file|roles/core/monitoring/files/prometheus-node-exporter.env}} || [https://prometheus.io/docs/ Prometheus documentation]
|-
| monitoring || Prometheus || {{Ops file|roles/core/monitoring/files/rc/prometheus-node-exporter.conf}} || [https://prometheus.io/docs/ Prometheus documentation]
|-
| network || dhclient || {{Ops file|roles/core/network/files/FreeBSD/dhclient6.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| network || dhclient || {{Ops file|roles/core/network/files/FreeBSD/dhclient6.service}} || [https://docs.freebsd.org/en/articles/rc-scripting/ RC scripting]
|-
| network || GRE tunnels || {{Ops file|roles/core/network/files/FreeBSD/gre.conf}} || [https://man.freebsd.org/cgi/man.cgi?gre gre man page]
|-
| network || GRE tunnels || {{Ops file|roles/core/network/files/FreeBSD/netif_gre.rc}} || [https://man.freebsd.org/cgi/man.cgi?gre gre man page]
|-
| network || Network || {{Ops file|roles/core/network/files/FreeBSD/netif_ipv4.rc}} || [https://docs.freebsd.org/en/books/handbook/network/ FreeBSD Handbook - Network]
|-
| network || Network || {{Ops file|roles/core/network/files/FreeBSD/netif_ipv6.rc}} || [https://docs.freebsd.org/en/books/handbook/network/ FreeBSD Handbook - Network]
|-
| network || Routing || {{Ops file|roles/core/network/files/FreeBSD/route-drake.service}} || [https://docs.freebsd.org/en/articles/rc-scripting/ RC scripting]
|-
| network || Routing || {{Ops file|roles/core/network/files/FreeBSD/route_drake.rc}} || [https://man.freebsd.org/cgi/man.cgi?route route man page]
|-
| network || Routing || {{Ops file|roles/core/network/files/FreeBSD/router.rc}} || [https://man.freebsd.org/cgi/man.cgi?route route man page]
|-
| network || Routing || {{Ops file|roles/core/network/files/FreeBSD/routing_ipv4.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| network || Routing || {{Ops file|roles/core/network/files/FreeBSD/routing_ipv6.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| network || Routing || {{Ops file|roles/core/network/files/Linux/routes.conf}} || [https://man7.org/linux/man-pages/man8/ip-route.8.html ip-route man page]
|-
| network || Routing || {{Ops file|roles/core/network/files/Linux/routes.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|-
| network || dhclient || {{Ops file|roles/core/network/files/dhclient6.conf}} || [https://man.freebsd.org/cgi/man.cgi?dhclient.conf dhclient.conf man page]
|-
| network || systemd || {{Ops file|roles/core/network/files/ipv6-tunnels/ipv6-tunnel.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|-
| ntp || NTP || {{Ops file|roles/core/ntp/files/rc/ntpd.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| pf || PF firewall || {{Ops file|roles/core/pf/files/pf.conf}} || [https://man.freebsd.org/cgi/man.cgi?pf.conf pf.conf man page]
|-
| pf || PF firewall || {{Ops file|roles/core/pf/files/rc/pf.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| pf || pflog || {{Ops file|roles/core/pf/files/rc/pflog.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| rc || locate || {{Ops file|roles/core/rc/files/locate.rc}} || [https://man.freebsd.org/cgi/man.cgi?locate.conf locate.conf man page]
|-
| rc || periodic || {{Ops file|roles/core/rc/files/periodic.conf}} || [https://man.freebsd.org/cgi/man.cgi?periodic.conf periodic.conf man page]
|-
| rsyslog || rsyslog || {{Ops file|roles/core/rsyslog/files/default.conf}} || [https://www.rsyslog.com/doc/ rsyslog documentation]
|-
| salt || Salt || {{Ops file|roles/core/salt/files/rc.conf}} || [https://docs.saltproject.io/ Salt documentation]
|-
| salt || Vault || {{Ops file|roles/core/salt/files/vault.conf}} || [https://developer.hashicorp.com/vault/docs Vault documentation]
|-
| sshd || SSH || {{Ops file|roles/core/sshd/files/rc.conf}} || [https://man.freebsd.org/cgi/man.cgi?sshd_config sshd_config man page]
|-
| sysctl || sysctl || {{Ops file|roles/core/sysctl/files/sysctl.conf}} || [https://man.freebsd.org/cgi/man.cgi?sysctl.conf sysctl.conf man page]
|-
| userland-home || nano || {{Ops file|roles/core/userland-home/files/dereckson/.nanorc}} || [https://www.nano-editor.org/dist/latest/nanorc.5.html nanorc man page]
|-
| userland-home || Zsh || {{Ops file|roles/core/userland-home/files/dereckson/.zshrc}} || [https://zsh.sourceforge.io/Doc/ Zsh documentation]
|-
| userland-home || tmux || {{Ops file|roles/core/userland-home/files/dorianwinty/.tmux.conf}} || [https://man.openbsd.org/tmux tmux man page]
|-
| userland-home || Zsh || {{Ops file|roles/core/userland-home/files/dorianwinty/.zshrc}} || [https://zsh.sourceforge.io/Doc/ Zsh documentation]
|-
| userland-software || pkg || {{Ops file|roles/core/userland-software/files/sources/FreeBSD.conf}} || [https://man.freebsd.org/cgi/man.cgi?pkg.conf pkg.conf man page]
|-
| userland-software || pkg || {{Ops file|roles/core/userland-software/files/sources/Nasqueron.conf}} || [https://man.freebsd.org/cgi/man.cgi?pkg.conf pkg.conf man page]
|-
| userland-software || tmux || {{Ops file|roles/core/userland-software/files/tmux.conf}} || [https://man.openbsd.org/tmux tmux man page]
|}

== dbserver-mysql ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| grc || grc || {{Ops file|roles/dbserver-mysql/grc/files/grcat.config}} || [https://github.com/garabik/grc grc documentation]
|-
| mysql-server || MySQL || {{Ops file|roles/dbserver-mysql/mysql-server/files/conf.d/client.cnf}} || [https://dev.mysql.com/doc/refman/en/ MySQL documentation]
|-
| mysql-server || MySQL || {{Ops file|roles/dbserver-mysql/mysql-server/files/conf.d/server.cnf}} || [https://dev.mysql.com/doc/refman/en/ MySQL documentation]
|-
| mysql-server || MySQL || {{Ops file|roles/dbserver-mysql/mysql-server/files/mysql.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| salt || Salt || {{Ops file|roles/dbserver-mysql/salt/files/mysql.conf}} || [https://docs.saltproject.io/ Salt documentation]
|}

== dbserver-pgsql ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| server || PostgreSQL || {{Ops file|roles/dbserver-pgsql/server/files/pg_hba.conf}} || [https://www.postgresql.org/docs/current/ PostgreSQL documentation]
|-
| server || PostgreSQL || {{Ops file|roles/dbserver-pgsql/server/files/postgresql.conf}} || [https://www.postgresql.org/docs/current/ PostgreSQL documentation]
|-
| server || PostgreSQL || {{Ops file|roles/dbserver-pgsql/server/files/postgresql.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|}

== devserver ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| api-exec || API-exec || {{Ops file|roles/devserver/api-exec/files/api-exec.conf}} || ''custom config, still to document''
|-
| api-exec || API-exec || {{Ops file|roles/devserver/api-exec/files/rc/api_exec.conf}} || [https://docs.freebsd.org/en/articles/rc-scripting/ RC scripting]
|-
| mail || Sendmail || {{Ops file|roles/devserver/mail/files/sendmail.rc}} || [https://man.freebsd.org/cgi/man.cgi?sendmail sendmail man page]
|-
| pkg || pkg || {{Ops file|roles/devserver/pkg/files/nasqueron.conf}} || [https://man.freebsd.org/cgi/man.cgi?pkg.conf pkg.conf man page]
|-
| poudriere || poudriere || {{Ops file|roles/devserver/poudriere/files/poudriere.conf}} || [https://github.com/freebsd/poudriere/wiki poudriere documentation]
|-
| userland-home || Git || {{Ops file|roles/devserver/userland-home/files/dereckson/.gitconfig}} || [https://git-scm.com/docs/git-config git-config documentation]
|-
| userland-home || Mercurial || {{Ops file|roles/devserver/userland-home/files/dereckson/.hgrc}} || [https://www.mercurial-scm.org/doc/hgrc.5.html hgrc man page]
|-
| userland-home || Shell || {{Ops file|roles/devserver/userland-home/files/dereckson/.shell.yml}} || ''custom config, still to document''
|-
| userland-home || tmux || {{Ops file|roles/devserver/userland-home/files/dereckson/.tmux.conf}} || [https://man.openbsd.org/tmux tmux man page]
|-
| userland-home || Zsh || {{Ops file|roles/devserver/userland-home/files/dereckson/.zshrc-misc-aliases}} || [https://zsh.sourceforge.io/Doc/ Zsh documentation]
|-
| userland-software || ccache || {{Ops file|roles/devserver/userland-software/files/ccache.conf}} || [https://ccache.dev/manual/latest.html ccache documentation]
|-
| userland-software || make || {{Ops file|roles/devserver/userland-software/files/make.conf}} || [https://man.freebsd.org/cgi/man.cgi?make.conf make.conf man page]
|-
| userland-software || Notifications || {{Ops file|roles/devserver/userland-software/files/notifications.conf}} || ''custom config, still to document''
|-
| userland-software || PEFS || {{Ops file|roles/devserver/userland-software/files/pefs.conf}} || [https://wiki.freebsd.org/PEFS PEFS documentation]
|-
| userland-software || Transmission || {{Ops file|roles/devserver/userland-software/files/transmission.rc}} || [https://github.com/transmission/transmission/blob/main/docs/Editing-Configuration-Files.md Transmission documentation]
|-
| userland-software || URL configuration || {{Ops file|roles/devserver/userland-software/files/url.yml}} || ''custom config, still to document''
|-
| webserver-home || nginx || {{Ops file|roles/devserver/webserver-home/files/001-server.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|}

== dns ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| knot || Knot DNS || {{Ops file|roles/dns/knot/files/knot.conf}} || [https://www.knot-dns.cz/docs/ Knot DNS documentation]
|-
| knot || Knot DNS || {{Ops file|roles/dns/knot/files/rc/knot.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|}

== grafana ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| grafana || Grafana || {{Ops file|roles/grafana/grafana/files/grafana.ini}} || [https://grafana.com/docs/grafana/latest/ Grafana documentation]
|-
| grafana || Grafana || {{Ops file|roles/grafana/grafana/files/rc/grafana.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|}

== mailserver ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| dkim || OpenDKIM || {{Ops file|roles/mailserver/dkim/files/opendkim.conf}} || [http://www.opendkim.org/opendkim.conf.5.html opendkim.conf man page]
|-
| dkim || OpenDKIM || {{Ops file|roles/mailserver/dkim/files/rc/opendkim.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| dovecot || Dovecot || {{Ops file|roles/mailserver/dovecot/files/conf.d/10-auth.conf}} || [https://doc.dovecot.org/ Dovecot documentation]
|-
| dovecot || Dovecot || {{Ops file|roles/mailserver/dovecot/files/conf.d/10-mail.conf}} || [https://doc.dovecot.org/ Dovecot documentation]
|-
| dovecot || Dovecot || {{Ops file|roles/mailserver/dovecot/files/conf.d/10-main-services.conf}} || [https://doc.dovecot.org/ Dovecot documentation]
|-
| dovecot || Dovecot || {{Ops file|roles/mailserver/dovecot/files/conf.d/10-metrics.conf}} || [https://doc.dovecot.org/ Dovecot documentation]
|-
| dovecot || Dovecot || {{Ops file|roles/mailserver/dovecot/files/conf.d/10-ssl.conf}} || [https://doc.dovecot.org/ Dovecot documentation]
|-
| dovecot || Dovecot || {{Ops file|roles/mailserver/dovecot/files/dovecot.conf}} || [https://doc.dovecot.org/ Dovecot documentation]
|-
| vimbadmin || ViMbAdmin || {{Ops file|roles/mailserver/vimbadmin/files/application.ini}} || [https://github.com/opensolutions/ViMbAdmin ViMbAdmin documentation]
|}

== netbox ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| netbox || NetBox || {{Ops file|roles/netbox/netbox/files/rc/netbox.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|}

== opensearch ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| dashboards || systemd || {{Ops file|roles/opensearch/dashboards/files/dashboards.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|-
| opensearch || OpenSearch || {{Ops file|roles/opensearch/opensearch/files/account.conf}} || [https://opensearch.org/docs/latest/ OpenSearch documentation]
|-
| opensearch || OpenSearch || {{Ops file|roles/opensearch/opensearch/files/opensearch.conf}} || [https://opensearch.org/docs/latest/ OpenSearch documentation]
|-
| opensearch || systemd || {{Ops file|roles/opensearch/opensearch/files/opensearch.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|}

== paas-docker ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| containers || Docker Compose || {{Ops file|roles/paas-docker/containers/files/relay/dev.yml}} || [https://docs.docker.com/compose/ Docker Compose documentation]
|-
| containers || Sentry || {{Ops file|roles/paas-docker/containers/files/sentry/etc/config.yml}} || [https://develop.sentry.dev/self-hosted/ Sentry self-hosted documentation]
|-
| containers || Symbolicator || {{Ops file|roles/paas-docker/containers/files/symbolicator/config.yml}} || [https://getsentry.github.io/symbolicator/ Symbolicator documentation]
|-
| containers || Vault || {{Ops file|roles/paas-docker/containers/files/vault/vault.hcl}} || [https://developer.hashicorp.com/vault/docs Vault documentation]
|-
| devel || systemd || {{Ops file|roles/paas-docker/devel/files/socket.conf}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|-
| kernel || tuned || {{Ops file|roles/paas-docker/kernel/files/tuned.conf}} || [https://tuned-project.org/ tuned documentation]
|-
| nginx || logrotate || {{Ops file|roles/paas-docker/nginx/files/logrotate/nginx.conf}} || [https://man.freebsd.org/cgi/man.cgi?logrotate logrotate man page]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/_default.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/acme_dns.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/auth-grove.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/base/fallback.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/base/server.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/bugzilla.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/cachet.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/etherpad.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/hauk.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/jenkins.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/notifications.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/openfire.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/orbeon.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/penpot_web.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/phabricator.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/pixelfed.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/rabbitmq.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/registry.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/sentry.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/tommy.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/paas-docker/nginx/files/vhosts/vault.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| systemd-timers || systemd || {{Ops file|roles/paas-docker/systemd-timers/files/report.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|-
| systemd-timers || systemd || {{Ops file|roles/paas-docker/systemd-timers/files/report.timer}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|-
| systemd-unit || systemd || {{Ops file|roles/paas-docker/systemd-unit/files/docker-containers.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|}

== paas-jails ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| jails || Jails || {{Ops file|roles/paas-jails/jails/files/ezjail.rc}} || [https://man.freebsd.org/cgi/man.cgi?jail jail man page]
|-
| jails || Jails || {{Ops file|roles/paas-jails/jails/files/jail.rc}} || [https://man.freebsd.org/cgi/man.cgi?jail jail man page]
|-
| jails || Network || {{Ops file|roles/paas-jails/jails/files/netif.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| jails || DNS resolver || {{Ops file|roles/paas-jails/jails/files/resolv.conf}} || [https://man.freebsd.org/cgi/man.cgi?resolv.conf resolv.conf man page]
|}

== prometheus ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| prometheus || Prometheus || {{Ops file|roles/prometheus/prometheus/files/prometheus.yml}} || [https://prometheus.io/docs/ Prometheus documentation]
|-
| prometheus || Prometheus || {{Ops file|roles/prometheus/prometheus/files/rc/prometheus.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| prometheus || newsyslog || {{Ops file|roles/prometheus/prometheus/files/syslog/newsyslog.conf}} || [https://man.freebsd.org/cgi/man.cgi?newsyslog.conf newsyslog.conf man page]
|-
| prometheus || newsyslog || {{Ops file|roles/prometheus/prometheus/files/syslog/prometheus.conf}} || [https://man.freebsd.org/cgi/man.cgi?newsyslog.conf newsyslog.conf man page]
|}

== redis ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| server || Redis || {{Ops file|roles/redis/server/files/redis.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|}

== reports ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| rhyne-wyse || Rhyne-Wyse || {{Ops file|roles/reports/rhyne-wyse/files/secrets.conf}} || [https://docs.nasqueron.org/secretsmith/connect.html#configuration-file secretsmith]
|-
| rhyne-wyse || Rhyne-Wyse || {{Ops file|roles/reports/rhyne-wyse/files/syslog/rhyne-wyse.conf}} || [https://man.freebsd.org/cgi/man.cgi?syslog.conf(5) syslog.conf]
|}

== router ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| carp || CARP || {{Ops file|roles/router/carp/files/carp.conf}} || [https://man.freebsd.org/cgi/man.cgi?carp carp man page]
|-
| carp || CARP || {{Ops file|roles/router/carp/files/carp.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| carp || CARP || {{Ops file|roles/router/carp/files/secrets.conf}} || [https://docs.nasqueron.org/secretsmith/connect.html#configuration-file secretsmith]
|}

== saas-mediawiki ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| nginx || nginx || {{Ops file|roles/saas-mediawiki/nginx/files/vhosts/nasqueron.org/agora.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/saas-mediawiki/nginx/files/vhosts/nasqueron.org/wikis.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/saas-mediawiki/nginx/files/vhosts/test.ook.space/mediawiki.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| saas || Environment || {{Ops file|roles/saas-mediawiki/saas/files/dot.env}} ||
|}

== salt-primary ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| api || Salt || {{Ops file|roles/salt-primary/api/files/api.conf}} || [https://docs.saltproject.io/ Salt documentation]
|-
| api || Salt || {{Ops file|roles/salt-primary/api/files/salt_api.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| config || Salt || {{Ops file|roles/salt-primary/config/files/pillar-tower.conf}} || [https://jgraichen.github.io/salt-tower/latest/tower/ salt-tower]
|-
| salt-wrapper || Salt || {{Ops file|roles/salt-primary/salt-wrapper/files/salt-wrapper.conf}} || [https://docs.nasqueron.org/salt-wrapper/admin.html#configuration-file salt-wrapper]
|}

== shellserver ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| database || MySQL || {{Ops file|roles/shellserver/database/files/my.cnf}} || [https://dev.mysql.com/doc/refman/en/ MySQL documentation]
|-
| odderon || systemd || {{Ops file|roles/shellserver/odderon/files/odderon.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|-
| odderon || Odderon || {{Ops file|roles/shellserver/odderon/files/servers.ini}} || [https://github.com/JiggyStardust/Odderon Odderon repository]
|-
| odderon || Odderon || {{Ops file|roles/shellserver/odderon/files/setup.ini}} || [https://github.com/JiggyStardust/Odderon Odderon repository]
|-
| userland-software || nano || {{Ops file|roles/shellserver/userland-software/files/nanorc}} || [https://www.nano-editor.org/dist/latest/nanorc.5.html nanorc man page]
|-
| userland-software || oidentd || {{Ops file|roles/shellserver/userland-software/files/oidentd.conf}} || [https://oidentd.janikrabe.com/doc/2.5/manual oidentd documentation]
|-
| userland-software || oidentd || {{Ops file|roles/shellserver/userland-software/files/oidentd.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| vault || Salt || {{Ops file|roles/shellserver/vault/files/salt-vault.conf}} || [https://docs.saltproject.io/ Salt documentation]
|-
| vault || Vault || {{Ops file|roles/shellserver/vault/files/salt.hcl}} || [https://developer.hashicorp.com/vault/docs Vault documentation]
|-
| vault || Vault || {{Ops file|roles/shellserver/vault/files/vault.hcl}} || [https://developer.hashicorp.com/vault/docs Vault documentation]
|-
| vault || systemd || {{Ops file|roles/shellserver/vault/files/vault.service}} || [https://www.freedesktop.org/software/systemd/man/ systemd documentation]
|-
| web-hosting || nginx || {{Ops file|roles/shellserver/web-hosting/files/eglide/nginx/vhosts/000-fallback.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| web-hosting || nginx || {{Ops file|roles/shellserver/web-hosting/files/eglide/nginx/vhosts/001-server.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|}

== vault ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| policies || Vault || {{Ops file|roles/vault/policies/files/admin.hcl}} || [https://developer.hashicorp.com/vault/tutorials/get-started/introduction-policies Vault policy]
|-
| policies || Vault || {{Ops file|roles/vault/policies/files/airflow.hcl}} || [https://developer.hashicorp.com/vault/tutorials/get-started/introduction-policies Vault policy]
|-
| policies || Vault || {{Ops file|roles/vault/policies/files/monitoring.hcl}} || [https://developer.hashicorp.com/vault/tutorials/get-started/introduction-policies Vault policy]
|-
| policies || Vault || {{Ops file|roles/vault/policies/files/salt-primary.hcl}} || [https://developer.hashicorp.com/vault/tutorials/get-started/introduction-policies Vault policy]
|-
| policies || Vault || {{Ops file|roles/vault/policies/files/sentry.hcl}} || [https://developer.hashicorp.com/vault/tutorials/get-started/introduction-policies Vault policy]
|-
| policies || Vault || {{Ops file|roles/vault/policies/files/vault_bootstrap.hcl}} || [https://developer.hashicorp.com/vault/tutorials/get-started/introduction-policies Vault policy]
|-
| vault || Vault || {{Ops file|roles/vault/vault/files/vault.hcl}} || [https://developer.hashicorp.com/vault/docs Vault documentation]
|}

== viperserv ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| eggdrop || Eggdrop || {{Ops file|roles/viperserv/eggdrop/files/eggdrop-bot.conf}} || [https://docs.eggheads.org/ Eggdrop documentation]
|-
| eggdrop || Eggdrop || {{Ops file|roles/viperserv/eggdrop/files/eggdrop-core.conf}} || [https://docs.eggheads.org/ Eggdrop documentation]
|-
| eggdrop || Eggdrop || {{Ops file|roles/viperserv/eggdrop/files/eggdrops-live.conf}} || [https://docs.eggheads.org/ Eggdrop documentation]
|}

== webserver-alkane ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| alkane || Alkane || {{Ops file|roles/webserver-alkane/alkane/files/alkane.conf}} || [[Operations grimoire/Alkane|Alkane]]
|-
| alkane || Alkane || {{Ops file|roles/webserver-alkane/alkane/files/alkane.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]

|-
| monitoring || PHP-FPM exporter || {{Ops file|roles/webserver-alkane/monitoring/files/rc/phpfpm_exporter.conf}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/newsyslog/nginx.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/dereckson.be/assets.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/dereckson.be/hg.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/dereckson.be/mediawiki.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/dereckson.be/scherzo.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/dereckson.be/www.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/dereckson.be/www51.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/dereckson.be/zed51.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/espace-win.org/cosmo.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/espace-win.org/grip.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/espace-win.org/www.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/hypership.space/www.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/admin.mail.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/api.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/api51.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/assets.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/autoconfig.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/daeghrefn.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/docker.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/docs.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/drive.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/ftp.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/grafana.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/infra.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/join.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/labs.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/launch.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/mail.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/obsidian51.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/packages.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/rain.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/tools51.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/trustspace.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/www.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/nasqueron.org/www51.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/test.ook.space/migration.mediawiki.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/wolfplex.org/api.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/wolfplex.org/assets.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-alkane/nginx/files/vhosts/wolfplex.org/www.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| php || PHP-FPM || {{Ops file|roles/webserver-alkane/php/files/php-fpm-pool.conf}} || [https://www.php.net/manual/en/install.fpm.configuration.php PHP-FPM documentation]
|-
| php || PHP-FPM || {{Ops file|roles/webserver-alkane/php/files/php-fpm.conf}} || [https://www.php.net/manual/en/install.fpm.configuration.php PHP-FPM documentation]
|-
| php || PHP-FPM || {{Ops file|roles/webserver-alkane/php/files/php.ini}} || [https://www.php.net/manual/en/configuration.file.php PHP configuration file]
|}

== webserver-content ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| _generic || Environment || {{Ops file|roles/webserver-content/_generic/files/dot.env}} || [https://github.com/vlucas/phpdotenv dotenv]
|-
| org/nasqueron || Git || {{Ops file|roles/webserver-content/org/nasqueron/files/git-safe.conf}} || [https://git-scm.com/docs/git-config git-config documentation]
|}

== webserver-core ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| nginx || nginx || {{Ops file|roles/webserver-core/nginx/files/nginx.conf}} || [https://nginx.org/en/docs/ nginx documentation]
|-
| nginx || nginx || {{Ops file|roles/webserver-core/nginx/files/nginx.rc}} || [[Operations grimoire/Services#FreeBSD_rc|FreeBSD rc]]
|}

== webserver-legacy ==

{| class="wikitable sortable"
! Unit !! Software !! Full path !! Documentation
|-
| php-sites || PHP-FPM || {{Ops file|roles/webserver-legacy/php-sites/files/php-fpm-pool.conf}} || [https://www.php.net/manual/en/install.fpm.configuration.php PHP-FPM documentation]
|-
| php-sites || PHP-FPM || {{Ops file|roles/webserver-legacy/php-sites/files/php-fpm.conf}} || [https://www.php.net/manual/en/install.fpm.configuration.php PHP-FPM documentation]
|-
| php-sites || PHP-FPM || {{Ops file|roles/webserver-legacy/php-sites/files/php.ini}} || [https://www.php.net/manual/en/configuration.file.php PHP configuration file]
|}

Operations grimoire/Services

2026-04-05T20:50:48Z

Dereckson: /* FreeBSD rc */ Basic instructions

Software running as daemons should be set as services to manage them at OS level a standard way.

== Systemd, rc and runit ==

Nasqueron infrastructure uses 3 services software:

{| class="wikitable"
|+ Service management
|-
! OS !! Use case !! Software !! Commands
|-
| FreeBSD || Standard || rc || service <service> <command>
|-
| Linux || Standard || systemd || systemctl <command> <service>
|-
| Linux || Docker containers || runit || sv <service> <command>
|}

Note how systemd inverts the general order by putting the command before the service.

== Systemd ==
=== Services ===
Search for .service file in operations repository for an idea.
It's well documented on ArchLinux wiki and freedesktop.org site.

References:
* https://www.freedesktop.org/software/systemd/man/latest/systemd.service.html
* https://wiki.archlinux.org/title/Systemd

=== Timers ===
* Generally better to use a systemd service and a systemd timer than a crontab entry on Linux
* Don't forget to start the timer, see [https://devcentral.nasqueron.org/D3674#57039 this comment on D3674] for a demonstration

=== Howto for operations repository ===
You can follow [https://www.dereckson.be/blog/2017/01/25/deploy-a-darkbot-or-a-simple-generic-service-with-saltstack-part-1/ this tutorial] to deploy a service on Nasqueron infrastructure, it covers the step from software deployment, configuration, user creation and a systemd service.

== FreeBSD rc ==
=== Structure of a rc configuration file ===
Each service is configured in /etc/rc.conf.d/<service> file or by all the files in /etc/rc.conf.d/<service>/ directory.

Those files follow [https://man.freebsd.org/cgi/man.cgi?rc.conf rc.conf syntax] and use:
* <service>_enable="YES" to indicate auto start of the service
* various <service>_<key>=<value> per service documentation

To know all the available options for a service the best is to read the documentation at the top of every service, located in
/usr/local/etc/rc.d for applications and /etc/rc.d for the base system.

=== Template for operations repository ===
If you need to add a rc service, we've a template for the file: follow [https://devcentral.nasqueron.org/D3571 D3571 instructions]

[[Category:Operations grimoire|Services]]

Operations grimoire

2026-04-05T20:41:45Z

Dereckson: /* Appendices */

[[File:Nasqueron Operations Grimoire.jpg|thumb|320px|right|The Nasqueron operations grimoire tries to document the more arcane aspects of our complex infrastructure.]]

Welcome to the Nasqueron operations grimoire (NOG).

This grimoire is a reference about our infrastructure and services hosted with procedures we follow to build, maintain and deploy.

Our infrastructure is open, mainly documented in {{repo|operations}} repository, and we actively encourage contributions from the community.

== Infrastructure ==
* [[/Environments]]
* [[/Kubernetes]]
* [[/Docker engine]]
* [[/Salt]]

=== OS-specific ===
;By OS
* [[/FreeBSD]]
* [[/RHEL]]

;All OSes
* [[/NTP]]
* [[/Packages repository]]
* [[/Services]]: systemd, runit and rc

=== Storage ===
* [[/ZFS]]

=== Observability ===
* [[/Grafana]]
* [[/Logs]]
* [[/Prometheus]]

=== Network ===
* [[/Network]]
* [[/DNS]]
* [[/Firewall]]
* [[/IPv6]]
* [https://netbox.nasqueron.org/ NetBox]

== Services ==
=== Core services ===
; Messages queues
* [[/Kafka]]
* [[/RabbitMQ]]

; Databases
* [[/MySQL]]
* [[/PostgreSQL]]

; Ops
* [[/NetBox]]

=== Identity management ===
* [[/Login]] (Auth Grove)

=== Collaborative tools ===
* [[/DevCentral]] (Phabricator)
* [[/Etherpad]]
* [[/Mumble]]
* [[/Mastodon]] (social.nasqueron.org)
* [[/Openfire]] (XMPP)

=== IRC bots ===
* [[/Dæghrefn]] (eggdrop)
* [[/Odderon]] (darkbot)

=== Mail ===
* [[/Mail]]
* [[/Mail/DKIM]]
* [[/Mail/Sympa]]

=== Web ===
; Common documentation for all webserver roles
* [[/Web/Headers]]

; Where to host?
* [[/Docker engine]] for Docker containers front-end
* [[/Alkane]] for PHP and static sites

; SaaS for common applications
* [[MediaWiki SaaS]]
* [[/WordPress]]

; Other sites
* [[/Sites on Eglide]]
* [[/Sites on Ysul]] (currently migrating to Alkane)

; Services for web applications
* [[/Anubis]] if you need to protect from LLM scraping traffic
* [[/Orbeon]] if you're in need of a form

=== CI/CD ===
* [[/Broker]]
* [[/Docker registry]]
* [[/Jenkins]]
* [[/Notifications center]]
* [[/Sentry]]
* [[/Vault]]

=== Shellserver ===
* [[/Eglide/Vault]]

== Services configuration ==
''This section contains general information not related to a specific service.''
* [[/TLS certificates]] (Let's encrypt / letsencrypt)

== Checklists ==
=== SSH ===
* [[/Recommended SSH configuration]]

=== Infrastructure ===
* [[/How to add a server to the Nasqueron servers pool]]
* [[/How to attach a new virtual disk]]
* [[/Reboot checklist]]

=== Network ===
* [[/Checklist router post-restart]]

=== Docker ===
* [[/Restart a Docker engine]]
* [[/Dwellers to DevCentral]]
* [[/Git operations in production containers]]
* [[/Add a service to Docker PaaS]]
* [[/Docker Hub]]

=== Salt ===
* [[/Operations repository]]
* [[/Deploy with Salt]]
* [[/Create and revoke user accounts on Salt servers]]
* [[/Provision user homefiles]]

=== Terraform / OpenTofu ===
* [[/Deploy with Terraform]]

== SIG ==
* [[/Onboarding]]

== Appendices ==
* [[/Changelog]]
* [[/Contacts]]
* [[/Configuration files]]
* [[/Contribute]]
* [[/Decom]]
* [[/Evaluated products]]
* [[/External services]]
* [[/Incidents]]
* [[/Legacy archive]]
* [[/OID]]
* [[/Old content report]]
* [[/Policies]]
* [[/Who]]

[[Category:Operations grimoire|*]]
[[Category:Reference]]

Code conventions

2026-04-03T22:35:38Z

Dereckson: /* Salt */ Double quotes

== All languages ==

* Don't use more complicated constructs like ternary operators
* [http://jeroendedauw.github.io/slides/craftmanship/functions/#/1 Keep functions short and simple].
* Define explicitly methods visibility, as several languages have different default values (e.g. private for C# class members, public for PHP methods)
* Comments to document a method are written at the singular 3rd person (we seem to have moved to infinitive recently, we need to take a decision here)

== C ==
If you use [http://clang.llvm.org/docs/ClangFormat.html ClangFormat], a [https://github.com/dereckson/rabbitmq-tcl/blob/master/.clang-format .clang-format file] is available.

== JavaScript ==
The following conventions are used:
* K&R, 1TBS variant, including for functions
* 4 spaces as indent
* Use modern JavaScript idioms like <code>const</code> and <code>let</code> instead of <code>var</code>
* Consider to use async code for events-driven development, especially for servers

== PHP ==
The following conventions are used:
* K&R, 1TBS variant, including for functions
* 4 spaces as indent
* The keywords <code>true</code>, <code>false</code> and <code>null</code> must be in lower case.
* Arrays use short syntax
* Array elements ends with a comma
* Functions, methods and class names use camel case

If you use PhpStorm or another JetBrains IDE, you can import [https://github.com/nasqueron/codestyle/blob/master/JetBrains/php-codestyle.xml JetBrains/php-codestyle.xml] from the codestyle repository as a code style (Settings or Default Settings > Editor > Code Style > PHP > click on the wheel icon > Import Scheme > Intellij IDEA codestyle XML).

If you want to lint a project with phpcs, you can require the Composer package <code>nasqueron/codestyle</code> and use the following <kbd>phpcs.xml<kbd> standard file:

<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<ruleset>
<rule ref="vendor/nasqueron/codestyle/CodeSniffer" />
<file>.</file>
<exclude-pattern>\.git/</exclude-pattern>
<exclude-pattern>vendor/</exclude-pattern>
</ruleset>
</syntaxhighlight>

== Python ==
=== Code style ===
'''2023.''' We follow [https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html black style], so use black utility (<code>pip install black</code>). As such, you need to configure Flake8 to ignore rule E203.

'''2015.''' We follow [https://www.python.org/dev/peps/pep-0008/ PEP-8].

=== Templates ===
A template exists for a new Python command: [https://devcentral.nasqueron.org/source/snippets/browse/main/python/command.py python/command.py]

In packages, empty __init__.py files can follow [https://devcentral.nasqueron.org/source/merge-dictionaries/browse/main/src/mergedictionaries/utils/__init__.py;eaf5bc2c21118454837e8148147606c19d4afff7 this example].

=== Configuration files ===
Allow empty configuration files. For example, the YAML parser will return None if the file exists but is empty, we can catch that and return default instead:

<syntaxhighlight lang="python">
with open(get_configuration_path()) as fd:
return yaml.safe_load(fd) or {}
</syntaxhighlight>

== Rust ==
'''2023.''' Automated codestyle (black in Python, clang-format in Rust) seems preferable. As such, a style compatible with <code>rustfmt</code> is needed to be able to format using <code>cargo fmt</code>. You can add to your project [https://devcentral.nasqueron.org/source/codestyle/browse/main/rust/rustfmt.toml rust/rustfmt.toml in codestyle] to configure it.

'''2015.''' We followed "Rust default style", described at [https://web.archive.org/web/20170320083740/http://aturon.github.io/ https://aturon.github.io/]. It's mainly a K&R, 1TBS variant.

Use trailing comma for elements in every struct/impl/etc.

=== Threads ===
Standard library isn't the most ergonomic for threads programming, those crate allows more efficient and legible code:
* [https://docs.rs/crossbeam-channel/latest/crossbeam_channel/ crossbeam_channel] for mpmc (multiple producers, multiple consumers)
* [https://docs.rs/parking_lot/latest/parking_lot/type.Mutex.html parking_lot] for Mutex

== Salt ==
=== Style ===
;Whitespaces
* Indent with two spaces
* YAML lists use indented bullets

<syntaxhighlight lang="yaml">
id:
method:
- somekey: value
- otherkey: value
</syntaxhighlight>

;Quotes
* Use double quotes in Python, Salt and Jinja expressions

=== Tips ===

;Files provisioned
* When you ask to download a file remotely, you need a source hash, pick SHA256 as algo
* Each file provisioned from the Salt repository must contains an header explaining the fact, with the full path in the rOPS repo

;BSD and Linux distros compatible states
* populate the map.jinja file with OS logic (e.g. `dirs` for /etc vs /usr/local/etc)
* when you've a specific set of tasks to do for one OS/distro, it's acceptable to enclose it in a state by an if block

=== Vocabulary ===

;Domain names
:To refer to the fully qualified domain name sub.domain.tld, use '''fqdn'''. To split the domains in part, use '''domain''' and '''subdomain'''. This is important to understand a state without having to refer to the associated pillar to disambig domain.

== Shell scripts ==
;UNIX agnosticism:
* Don't assume absolute path, use <code>#!/usr/bin/env bash</code> and not <code>#!/bin/bash</code> (it could be elsewhere on BSD or Solaris)
* Use `sh` as must as possible, try to avoid <code>bash</code>, document exceptions rationale in your commits

;Whitespaces:
* One whitespace line between shebang and actual content
* 4 spaces as indent

;File names:
* We use hyphens (-) as separators, not underscores or camelcase
* Filename should start by a verb if it performs an action
* Don't use .sh extensions when deployed as command
** sometimes you'll see them on Phabricator pastes' titles, but it has been added there, so Phab knows shell syntax highlighting should be used
** '''Tip.''' You can use .sh in src/ to help linters, but then provide a Makefile to install it under correct name without extension. Same for operations repository where everything uses .sh, but when deploying with file.managed the extension is omitted

;Templates
* New command: [https://devcentral.nasqueron.org/source/snippets/browse/main/shell/script.sh shell/script.sh]

== TCL ==

* Indent with 4 spaces, as of 2026-03-20
* Keep blocks visually separated
* Use Tcl primitives instead of manual parsing for strings: split, lindex, lrange, join
* Avoid regex unless necessary
* List expansion {*} instead of eval

; ViperServ development
* If you build a full new system, all procedures must be defined in a namespace
* Use fully-qualified names (::namespace::proc) for procedure definitions and cross-namespace calls
* Separate low-level request logic from API-specific methods

== Makefile ==
UNIX agnosticism:
* Test your makefile against BSD make, and document in README.md to use GNU Makefile (gmake) when it's not convenient to keep compatibility

Presentation:
* Create a block with the general targets, then sections with your targets organized by categories/goals/parts

Tip:
* It's possible to provision BSDmakefile and GNUmakefile when UNIX agnosticism doesn't work.

== Structured data formats (YAML, JSON, XML) ==
The number of spaces depend if the format is usually heavily hierarchized or not:

* 2 spaces for JSON and YAML
* 4 spaces for XML, TOML and other configuration files

== Utilities ==

The https://github.com/nasqueron/codestyle repository contains resource to help to respect code convention, like a phpcs ruleset, a configuration ready for PhpStorm, IntelliJ and other JetBrains editors, or a clang-format configuration file.

== Troubleshoot ==
=== Fix indent issues ===
The <code>expand</code> utility converts tabs into spaces, while <code>unexpand</code> convert spaces into tabs.

Switch a file from tab indent to 4 spaces indent:

$ expand -t 4 foo.sh > a
$ cat a > foo.sh
$ rm a

(Avoid <code>mv</code> for shell scripts as your foo.sh has probably a 755 chmod, and a will probably have a 644 chmod, assuming 022 as umask)

Switch a file indent with 2 spaces to 4 spaces:

$ unexpand -t 2 JetBrains/php-codestyle.xml > a
$ expand -t 4 a > JetBrains/php-codestyle.xml

This last technique can be used in batch [https://gist.github.com/dereckson/80a746b408c0cf0b688a09db31d5c881 with this reindent script]:

$ git ls-files | xargs -n1 reindent 2 4

[[Category:Reference]]
[[Category:Contributor guide]]

WindRiver

2026-04-03T17:19:51Z

Dereckson:

WindRiver is an FreeBSD 14 bare metal server for Nasqueron general-purpose development.

It supersedes [[Ysul]].

Documentation: [[Devserver reference]]

== Basic information ==
* '''IP:'''
** 195.154.30.15 <strike>51.159.17.168 since 2023-06-14. Previously 51.159.18.59.</strike>
** 2a02:578:4f0d:0:30d0:7b22:6cde:a52e (native, still to migrate)
** 2001:bc8:6005:5:aa1e:84ff:fef3:5d9c (future through HE)
* '''Hostname:''' windriver.nasqueron.org
* '''Homepage:''' https://windriver.nasqueron.org/
* '''Configuration:''' <strike>64 Gb RAM, Xeon E3 1240 V6, 2x 500 GB SSD ("Pro-6-S")</strike> 96 Gb. RAM, Xeon E5-1650 v3, 3x 500 GB SSD ("Pro-4-L")
* '''ISP:''' [http://www.online.net Online] (FR)
* '''Network:''' Illiad (FR)
* '''Policy:''' Access for any Nasqueron project and for infrastructure operations task.
* '''Started:''' 2019-11-21

== Ports ==

Ports for services managed automatically through Salt are available on {{Ops file|PORTS}}

{| class="wikitable"
|+ Reserved ports - IRC server range
|-
! Port !! User account !! Description
|-
| 6901 || dereckson || irssi proxy
|-
| 6902 || dereckson || irssi proxy
|}

== Troubleshoot ==

=== To check after reboot ===

* Network
** IPv4 - ICANN
** IPv6 - main + viperserv alias
** IPv6 - can we reach something with IPv6
** IPv4 - Drake: tunnel + route + ping any server
* Services
** Alkane HTTP server
** API exec HTTP server
** Bitlbee
** Eggdrops: Dæghrefn + Wearg
** Grafana
** MariaDB
** NetBox
** nginx
** Node exporter for Prometheus
** oidentd
** php-fpm
** PostgreSQL
** Prometheus
** Redis
** Salt minion
** SSH server
* Vault connectivity

How to communicate

2026-03-24T17:13:32Z

Dereckson:

This page shows tools and best practices to communicate efficiently about code changes or operations activities.

== Ways of communication ==

=== Discussion spaces ===
Our primary discussion spaces are IRC, DevCentral and here on Agora:

{| class="wikitable"
|+ Primary discussion spaces
|-
! Space !! How to join !! Scope
|-
| [[IRC]] || [https://libera.chat/ Libera.chat] #nasqueron-ops || Discussions about servers, infrastructure, operations, access.<br>Also, as it's currently our main discussion space, you're welcome to hangout there if you want to chat with fellow nasquenautes.
|-
| DevCentral || Browse https://devcentral.nasqueron.org || Tasks, project management, status update, sprints, ideas
|-
| Agora || You're here! [https://forms.nasqueron.org/nasqueron-requests/agora-account/new Request an account] || Documentation, projects, idea, personal notes
|}

We also use Jitsi as video-conference platform and some members currently use Discord to organize their contributions:

{| class="wikitable"
|+ Known discussion spaces
|-
! Space !! How to join !! Scope
|-
|-
| Discord || https://discord.gg/DZQK8Dd8Xd || ServPulse
|-
| Jitsi || https://meet.jit.si/nasqueron || Any topic.<br>Tip: If you're first on the meeting, you can login through GitHub to open it.
|}
=== By project ===
* Nasqueron Operations SIG uses IRC: Libera.chat #nasqueron-ops
* Eli and Amine work on Discord for [[ServPulse]]

=== Tips for audio and video meeting ===
A headset can help a lot to get clear communication, without echo or reverb. When you don't have it, try to mute yourself when you don't speak (Jitsi) or enable push-to-talk feature (Discord).

Dereckson has a spare USB headset from Sennheiser if you need one.

== Share logs, screenshots ==
;Core recommandations
* DO: use appropriate tools to share information through a short link
* DON'T: use screenshots to share text, text must be shared as text
* DON'T: copy/paste full logs in chat
* DON'T: share logs with privacy data / PII, in that case give a reference to go to that log

;Tools to use
* To share directly the ouput of a command
** [https://termbin.com/ Termbin]: <code>command | nc termbin.com 9999</code>
** Arcanist to publish to DevCentral: <code>command | arc paste --</code>
* To share clipboard content
** https://dpaste.com/
** DevCentral: [https://devcentral.nasqueron.org/paste/edit/form/default/ create paste], that gives a reference to put in other objects (tasks, differential), use <code>{P100}</code> for direct inclusion or <code>P100</code> for link
* To share source code
** Pastebin are totally appropriated too
** You can also use GitHub Gist: https://gist.github.com - they can be secret or publicly available
** You can send a pull request to the repository for proof of concept
** If you want to discuss a pull request against an upstream repository, DevCentral allows "free" diff not linked to any repo too: [https://devcentral.nasqueron.org/differential/diff/create/ diff/create]

;Too many tools! I'm lost
It can require some practice to be able to pick among the most appropriate tool, so you can start with:
* Command output -> <code>command | nc termbin.com 9999</code>
* Anything else
** Ephemeral -> https://dpaste.com/
** To save and discuss in tasks -> https://devcentral.nasqueron.org/paste/edit/form/default/

[[Category:Contributor guide]]
[[Category:Reference]]

Operations grimoire/Deploy with Terraform

2026-03-22T23:51:29Z

Dereckson: /* Propagate secrets (DRP) */

== Where to work? ==
We deploy from [[Complector]] using <code>/opt/salt/nasqueron-operations</code> as our local copy of rOPS, authoritative for both Salt and Terraform

You need to belong to the <code>ops</code> group to be able to have access and have write-rights on the repository

It's important to work from there to save a shared Terraform state.

== Specific deployment notes ==
=== Vault / OpenBao ===
==== General notes ====
;OpenTofu support
As of 2026-02-07, the Vault provider isn't compiled for FreeBSD. You need to use Terraform instead.

;Vault
You need a Vault token to allow the provider to connect.

You also need to set VAULT_ADDR to https://172.27.27.7:8200 as Vault doesn't listen on 127.0.0.1

<syntaxhighlight lang="shell">
$ export VAULT_ADDR=https://172.27.27.7:8200
$ sudo /opt/salt/nasqueron-operations/utils/vault/issue-admin-token.py > ~/.vault-token

$ cd /opt/salt/nasqueron-operations/terraform/openbao
$ terraform init # if you've a new entry requiring a module, it needs to be installed
$ terraform plan
$ terraform apply
</syntaxhighlight>

It could be interesting to maintain an alternative policy to admin for the Terraform provider, restricted to the current actions. Note benefits would be limited as those include policies management.

==== Propagate secrets (DRP) ====
;No automatic secret rotation
Secrets rotation is disabled with a lifecycle management <code>ignore_changes = [ secret_id, ]</code>.

To rotate a secret, it needs first to be destroyed from terraform state:
<code>terraform destroy -target=module.viperserv_approle.vault_approle_auth_backend_role_secret_id.this</code>

;Full procedure
Once the AppRole have been created in Vault, they need to be provisioned to the relevant configuration files.

<syntaxhighlight lang="shell">
$ cd /opt/salt/nasqueron-operations/terraform/openbao
$ terraform init # if you've a new entry requiring a module, it needs to be installed
$ terraform plan
$ terraform apply

$ cd /opt/salt/nasqueron-operations
$ salt windriver state.sls_id /usr/local/etc/secrets/rhyne-wyse.yaml roles/reports/rhyne-wyse/config
$ salt windriver state.sls_id /srv/viperserv/.credentials roles/viperserv/eggdrop/config
# Missing for router
</syntaxhighlight>

<div class="alert">Important. Each time you'll reprovision the secrets, they will change.

Don't forget to always apply this full procedure.
</div>

== Table of Terraform states ==

{| class="wikitable"
|+ Terraform and OpenBao states
|-
! Configuration !! State back-end !! Path !! Software to use
|-
| openbao || On disk || /opt/salt/nasqueron-operations/terraform/openbao/terraform.tfstate || Terraform
|}

On disk paths are stored in Complector.

== Troubleshoot ==
=== Error: Module not installed ===

You need to run <code>tofu init</code> to prepare for any new provider.

<syntaxhighlight lang="shell">
$ tofu plan

│ Error: Module not installed
│
│ on rhyne_wyse.tf line 23:
│ 23: module "rhyne_wyse_approle" {
│
│ This module is not yet installed. Run "tofu init" to install all modules required by this configuration.
</syntaxhighlight>

=== Error: Incompatible provider version ===

<syntaxhighlight lang="shell">
$ tofu init

Initializing the backend...
Initializing modules...
- rhyne_wyse_approle in modules/app_credentials

Initializing provider plugins...
- Finding hashicorp/vault versions matching "5.3.0"...
╷
│ Error: Incompatible provider version
│
│ Provider registry.opentofu.org/hashicorp/vault v5.3.0 does not have a package available for your current platform, freebsd_amd64.
│
│ Provider releases are separate from OpenTofu CLI releases, so not all providers are available for all platforms. Other versions of this provider may have different platforms supported.
</syntaxhighlight>

On OpenTofu, some modules are only compiled for Linux, not for FreeBSD.
Switch to Terraform pending a solution to help the OpenTofu builds.

[[Category:Operations grimoire]]
[[Category:Terraform]]

MediaWiki:Common.css

2026-03-22T23:50:38Z

Dereckson:

/* Source code */

code, tt, kbd, pre, samp {
font-size: 0.9em !important;
}

/* Call for actions button */

.btn {
-webkit-border-radius: 6;
-moz-border-radius: 6;
border-radius: 6px;
color: #ffffff;
font-size: 1.4em;
background: #4d7b94;
padding: 10px 20px 10px 20px;
text-decoration: none;
}

.btn a, .btn a:hover, .btn a:visited {
color: white !important;
}

.btn:hover {
background: #6caacc;
text-decoration: none;
}

/* Inline code */

.inline-code, .inline-code div, .inline-code pre {
display: inline-table;
}

/*
Banners
*/

.alert {
background: #d32f2f;
color: #fff;
padding: 0.75rem 1rem;
border-radius: 4px;
font-weight: 600;
}

/*
Colors from 2017 palette

See https://devcentral.nasqueron.org/M11 or [[Design/2017 colors]]
*/

.color-magnetic-one {
/* Cyberspace gray */
color: #44484D;
}
.color-magnetic-two {
/* Anchors Aweigh blue */
color: #2B3441;
}
.color-magnetic-three {
/* Niagara blue — Pantone 17-4123 */
color: #5587A2;
}
.color-magnetic-four {
/* Primrose yellow — Pantone 13-0755 */
color: #F6D258;
}
.color-magnetic-five {
/* Green from http://www.elledecor.com/design-decorate/color/g3175/color-trends/ */
color: #67947D;
}

/*
Responsive blocks.
*/

.block {
margin: 0 0;
padding: 5vh 5vw;

border: #808080 solid 5px;
}

.block-col {
position: relative;
display:inline;
float: left;
margin-right: 1em;
padding: 1vw;
}

.block-col-quarter {
width: 20%;
}

.block-col-half {
width: 40%;
}

.user-block {
min-height: 50vh;
background-color: #44484D;
color: white;
}

.user-block dt {
color: #67947D;
font-family: 'Segoe UI', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Lato', 'Liberation Sans', 'Noto Sans', 'Helvetica Neue', 'Helvetica', sans-serif;
font-size: 1.375em;
margin-bottom: 1em;
}

.user-block a {
color: #F6D258 !important;
}

/*
Variable Grid System.
Learn more ~ http://www.spry-soft.com/grids/
Based on 960 Grid System - http://960.gs/

Licensed under GPL and MIT.
*/

/* Containers
----------------------------------------------------------------------------------------------------*/
.container_12 {
margin-left: auto;
margin-right: auto;
width: 960px;
}

/* Grid >> Global
----------------------------------------------------------------------------------------------------*/

.grid_1,
.grid_2,
.grid_3,
.grid_4,
.grid_5,
.grid_6,
.grid_7,
.grid_8,
.grid_9,
.grid_10,
.grid_11,
.grid_12 {
display:inline;
float: left;
position: relative;
margin-left: 10px;
margin-right: 10px;
}

/* Grid >> Children (Alpha ~ First, Omega ~ Last)
----------------------------------------------------------------------------------------------------*/

.alpha {
margin-left: 0;
}

.omega {
margin-right: 0;
}

/* Grid >> 12 Columns
----------------------------------------------------------------------------------------------------*/

.container_12 .grid_1 {
width:60px;
}

.container_12 .grid_2 {
width:140px;
}

.container_12 .grid_3 {
width:220px;
}

.container_12 .grid_4 {
width:300px;
}

.container_12 .grid_5 {
width:380px;
}

.container_12 .grid_6 {
width:460px;
}

.container_12 .grid_7 {
width:540px;
}

.container_12 .grid_8 {
width:620px;
}

.container_12 .grid_9 {
width:700px;
}

.container_12 .grid_10 {
width:780px;
}

.container_12 .grid_11 {
width:860px;
}

.container_12 .grid_12 {
width:940px;
}

/* Prefix Extra Space >> 12 Columns
----------------------------------------------------------------------------------------------------*/

.container_12 .prefix_1 {
padding-left:80px;
}

.container_12 .prefix_2 {
padding-left:160px;
}

.container_12 .prefix_3 {
padding-left:240px;
}

.container_12 .prefix_4 {
padding-left:320px;
}

.container_12 .prefix_5 {
padding-left:400px;
}

.container_12 .prefix_6 {
padding-left:480px;
}

.container_12 .prefix_7 {
padding-left:560px;
}

.container_12 .prefix_8 {
padding-left:640px;
}

.container_12 .prefix_9 {
padding-left:720px;
}

.container_12 .prefix_10 {
padding-left:800px;
}

.container_12 .prefix_11 {
padding-left:880px;
}

/* Suffix Extra Space >> 12 Columns
----------------------------------------------------------------------------------------------------*/

.container_12 .suffix_1 {
padding-right:80px;
}

.container_12 .suffix_2 {
padding-right:160px;
}

.container_12 .suffix_3 {
padding-right:240px;
}

.container_12 .suffix_4 {
padding-right:320px;
}

.container_12 .suffix_5 {
padding-right:400px;
}

.container_12 .suffix_6 {
padding-right:480px;
}

.container_12 .suffix_7 {
padding-right:560px;
}

.container_12 .suffix_8 {
padding-right:640px;
}

.container_12 .suffix_9 {
padding-right:720px;
}

.container_12 .suffix_10 {
padding-right:800px;
}

.container_12 .suffix_11 {
padding-right:880px;
}

/* Push Space >> 12 Columns
----------------------------------------------------------------------------------------------------*/

.container_12 .push_1 {
left:80px;
}

.container_12 .push_2 {
left:160px;
}

.container_12 .push_3 {
left:240px;
}

.container_12 .push_4 {
left:320px;
}

.container_12 .push_5 {
left:400px;
}

.container_12 .push_6 {
left:480px;
}

.container_12 .push_7 {
left:560px;
}

.container_12 .push_8 {
left:640px;
}

.container_12 .push_9 {
left:720px;
}

.container_12 .push_10 {
left:800px;
}

.container_12 .push_11 {
left:880px;
}

/* Pull Space >> 12 Columns
----------------------------------------------------------------------------------------------------*/

.container_12 .pull_1 {
left:-80px;
}

.container_12 .pull_2 {
left:-160px;
}

.container_12 .pull_3 {
left:-240px;
}

.container_12 .pull_4 {
left:-320px;
}

.container_12 .pull_5 {
left:-400px;
}

.container_12 .pull_6 {
left:-480px;
}

.container_12 .pull_7 {
left:-560px;
}

.container_12 .pull_8 {
left:-640px;
}

.container_12 .pull_9 {
left:-720px;
}

.container_12 .pull_10 {
left:-800px;
}

.container_12 .pull_11 {
left:-880px;
}

/* Clear Floated Elements
----------------------------------------------------------------------------------------------------*/

/* http://sonspring.com/journal/clearing-floats */

.clear {
clear: both;
display: block;
overflow: hidden;
visibility: hidden;
width: 0;
height: 0;
}

/* http://perishablepress.com/press/2008/02/05/lessons-learned-concerning-the-clearfix-css-hack */

.clearfix:after {
clear: both;
content: ' ';
display: block;
font-size: 0;
line-height: 0;
visibility: hidden;
width: 0;
height: 0;
}

.clearfix {
display: inline-block;
}

* html .clearfix {
height: 1%;
}

.clearfix {
display: block;
}

Operations grimoire/Deploy with Terraform

2026-03-22T23:18:13Z

Dereckson: /* Propagate secrets (DRP) */ # Missing for router

== Where to work? ==
We deploy from [[Complector]] using <code>/opt/salt/nasqueron-operations</code> as our local copy of rOPS, authoritative for both Salt and Terraform

You need to belong to the <code>ops</code> group to be able to have access and have write-rights on the repository

It's important to work from there to save a shared Terraform state.

== Specific deployment notes ==
=== Vault / OpenBao ===
==== General notes ====
;OpenTofu support
As of 2026-02-07, the Vault provider isn't compiled for FreeBSD. You need to use Terraform instead.

;Vault
You need a Vault token to allow the provider to connect.

You also need to set VAULT_ADDR to https://172.27.27.7:8200 as Vault doesn't listen on 127.0.0.1

<syntaxhighlight lang="shell">
$ export VAULT_ADDR=https://172.27.27.7:8200
$ sudo /opt/salt/nasqueron-operations/utils/vault/issue-admin-token.py > ~/.vault-token

$ cd /opt/salt/nasqueron-operations/terraform/openbao
$ terraform init # if you've a new entry requiring a module, it needs to be installed
$ terraform plan
$ terraform apply
</syntaxhighlight>

It could be interesting to maintain an alternative policy to admin for the Terraform provider, restricted to the current actions. Note benefits would be limited as those include policies management.

==== Propagate secrets (DRP) ====
;No automatic secret rotation
Secrets rotation is disabled with a lifecycle management <code>ignore_changes = [ secret_id, ]</code>.

To rotate a secret, it needs first to be destroyed from terraform state:
<code>terraform destroy -target=module.viperserv_approle.vault_approle_auth_backend_role_secret_id.this</code>

;Full procedure
Once the AppRole have been created in Vault, they need to be provisioned to the relevant configuration files.

<syntaxhighlight lang="shell">
$ cd /opt/salt/nasqueron-operations/terraform/openbao
$ terraform init # if you've a new entry requiring a module, it needs to be installed
$ terraform plan
$ terraform apply

$ cd /opt/salt/nasqueron-operations
$ salt windriver state.sls_id /usr/local/etc/secrets/rhyne-wyse.yaml roles/reports/rhyne-wyse/config
$ salt windriver state.sls_id /srv/viperserv/.credentials roles/viperserv/eggdrop/config
# Missing for router
</syntaxhighlight>

== Table of Terraform states ==

{| class="wikitable"
|+ Terraform and OpenBao states
|-
! Configuration !! State back-end !! Path !! Software to use
|-
| openbao || On disk || /opt/salt/nasqueron-operations/terraform/openbao/terraform.tfstate || Terraform
|}

On disk paths are stored in Complector.

== Troubleshoot ==
=== Error: Module not installed ===

You need to run <code>tofu init</code> to prepare for any new provider.

<syntaxhighlight lang="shell">
$ tofu plan

│ Error: Module not installed
│
│ on rhyne_wyse.tf line 23:
│ 23: module "rhyne_wyse_approle" {
│
│ This module is not yet installed. Run "tofu init" to install all modules required by this configuration.
</syntaxhighlight>

=== Error: Incompatible provider version ===

<syntaxhighlight lang="shell">
$ tofu init

Initializing the backend...
Initializing modules...
- rhyne_wyse_approle in modules/app_credentials

Initializing provider plugins...
- Finding hashicorp/vault versions matching "5.3.0"...
╷
│ Error: Incompatible provider version
│
│ Provider registry.opentofu.org/hashicorp/vault v5.3.0 does not have a package available for your current platform, freebsd_amd64.
│
│ Provider releases are separate from OpenTofu CLI releases, so not all providers are available for all platforms. Other versions of this provider may have different platforms supported.
</syntaxhighlight>

On OpenTofu, some modules are only compiled for Linux, not for FreeBSD.
Switch to Terraform pending a solution to help the OpenTofu builds.

[[Category:Operations grimoire]]
[[Category:Terraform]]

Operations grimoire/Vault

2026-03-22T18:59:45Z

Dereckson: /* Get an admin-level token */

''This page currently documents Vault installed on complector as part of {{Ops file|roles/vault/}}. It doesn't document Docker or shellserver installation. See [[Operations grimoire/Eglide/Vault]] and [[Dev zone/Vault]].''

Hashicorp Vault allows to manage credentials and is currently used:

* to provision credentials through Salt
* to allow applications to fetch credentials
* to emit certificates for the private network applications
* to store credentials used by the Nasqueron Operations SIG beings

Vault policies are fully managed through Salt in the operations repository.

Vault has been selected in 2016 for secrets management.

== Vault reference ==
=== kv engine ===
The kv engine contains the following paths:

* ops/secrets: credentials like passwords, API tokens, private keys deployed to servers - a reference for machines
* ops/internal: credentials to third-party services internally shared amongst ops - a reference for humans
* ops/privacy: privacy information

==== Secrets ====
Secrets are directly and manually managed in Vault. If we need to run a disaster recovery procedure, we'll roll any secret by defining them again and deploy from rOPS those new secrets.

==== Privacy data ====
Personal identity information (PII) shared inside the Nasqueron Operations squad are more convenient to manage as a repository.

Such access to the repository is restricted to commit data, and ensure this data is deployed to the servers needing it. Any other use isn't allowed.

Information to the repository is then published in Vault, and referred in rOPS as Vault credentials.

'''Note:''' The ops/privacy path is only intended for PII of current or previous members of the Ops SIG, like IP addresses allowed to connect to restricted resources like the ops VPN. This is not acceptable to put 3rd party information in this repository.

=== pki engine ===
Services listening to private IPs use the Vault PKI to generate certificates:

* pki_root: root CA, certificate available at https://api.nasqueron.org/infra/security/pki/root/ca
* pki_vault: intermediate CA used for Vault itself

Certificates should be issued short-term and frequently renewed by automated services.

=== transit engine ===
Encryption as a service is available for applications under /transit path.

See https://learn.hashicorp.com/tutorials/vault/eaas-transit.

Applications should use a policy restricting to a subpath for that app, not to the whole engine.

=== Users accounts ===

Members of the Operations SIG need an access to Vault to create and maintain credentials.

Currently, we use tokens. To generate a token:

vault token create -policy=admin

To connect to Vault with a token from a devserver (e.g. WindRiver), you need:

# Store the token in <code>$HOME/.vault-token</code>
# Define environment variable VAULT_ADDR: <code>export VAULT_ADDR=https://172.27.27.7:8200</code>

Tokens need to be frequently renew (before expiration) with <code>vault renew</code>

== Salt configuration ==
=== Get a secret through Salt ===
The information in the ops/secrets and ops/privacy kv engines are integrated in the Salt pillar:

<syntaxhighlight lang="yaml">
ext_pillar:
# Credentials to deploy to servers
- vault:
conf: path=ops/secrets
nesting_key: credentials

# Personal identity information from Nasqueron Operations SIG members
- vault:
conf: path=ops/privacy
nesting_key: privacy
</syntaxhighlight>

You can then access to this information in Salt states using the following references:

{| class="wikitable"
|+ Access to Salt data
|-
! Category !! Example of path in Vault !! Example of pillar key in Salt
|-
| Secrets || ops/secrets/foo || pillar['credentials']['foo']
|-
| Privacy data || ops/privacy/ops-cidr || pillar['privacy']['ops-cidr']
|}

The ops/internal paths aren't accessible through Vault.

=== Policies ===

Policies are managed in {{Ops file|pillar/credentials/vault.sls}}.

For Salt, we deploy secrets to servers, policy management for a node consist to provide the list of secrets a role should have access to, generally in '''vault_secrets_by_role''' dictionary.

For other applications:
* create a policy .hcl in <code>roles/vault/policies/files/</code>
* declare the policy in the pillar under <code>vault_policies</code> list, it should match the .hcl file (without the extension or the path)
* run the repository tests to check if both information matches ; to only run that part, use <code>cd _tests && python3 -m unittest discover pillar/credentials/</code>

To add only an application policy, Salt can be deployed like this:

salt complector state.sls_id vault_policy_airflow roles/vault/policies

Salt policies can be tested by specifying the node name:

salt complector state.sls_id salt-node-windriver roles/vault/policies test=True

=== DRP ===
Any step we need to do to configure the engines should be added to the {{ops file|roles/vault/bootstrap}} unit.

If we need to recover Vault, two solutions are available:
* restore the storage, to keep data (credentials, certificates including the root CA one)
* recreate it from scratch through the roles/vault/bootstrap unit

== Howto ==
=== Allow a new application to authenticate to Vault ===
Applications need a policy and an authentication method, for example here for an application called yourservice with AppRole with secret_id and role_id:
# Create a new policy in operations repository: {{D|3270}}
# Deploy it from Complector with <code>salt complector state.sls_id vault_policy_yourservice roles/vault/policies</code>
# Create an approle matching that policy: <code>vault write auth/approle/role/yourservice token_policies="yourservice" token_ttl=1h token_max_ttl=4h</code>
# Get role_id with <code>vault read auth/approle/role/yourservice/role-id</code>
# Get secret_id with <code>vault write -force auth/approle/role/yourservice/secret-id</code>
# If you wish Salt to provision those credentials during your service deployment, probably a good idea to write them too: <code>vault kv put secrets/nasqueron/yourservice/vault username=role-id password=secret-id</code> [to skip if you don't use Salt to provision role-id and secret-id]

=== Get an admin-level token ===
Ops can use the self-service hvac script to get a token valid for 30 days:

ssh complector
cd /opt/salt/nasqueron-operations
sudo ./utils/vault/issue-admin-token.py

If Vault certificate has expired, add the `--insecure` argument.

You can also create a $HOME/bin/vault-login helper script:

<syntaxhighlight language="sh">
#!/bin/sh

touch $HOME/.vault-token
chmod 600 $HOME/.vault-token
ssh complector sudo /opt/salt/nasqueron-operations/utils/vault/issue-admin-token.py | tr -d '\n' > $HOME/.vault-token
</syntaxhighlight>

== Troubleshoot ==
=== Connecting to Vault ===
==== Access to web UI ====
Vault isn't listening any public IP, but accept connections from internal network, so you can open a SSH tunnel against <code>complector:8200</code> and then browse https://localhost:8200:

<code>ssh -L 8200:complector:8200 router-001.nasqueron.org</code>

==== curl: (60) SSL certificate problem ====
Curl is compiled against a certificate bundle (<code>curl-config --ca</code> for the path). That bundle doesn't contain the pki_root certificate. We deploy this certificate in /etc/ssl/certs, but curl won't check there if not instructed to.

If you build an immutable environment like a container, add the certificate to the bundle.

On other machines, create a curl configuration file in ~/.curlrc (it doesn't seem currently possible to create a system one) with <code>capath=/etc/ssl/certs</code>.

If you've still the issue after that, check two things:
* with <code>curl -v</code>, the path should correctly there: <code>* CApath: /etc/ssl/certs</code> in addition to a CAfile.
* with <code>file /etc/ssl/certs/* | grep -i nasqueron</code> you should have a result ; if not, put the certificate in /usr/local/share/certs and relaunch the tool to link it in /etc/ssl/certs, for example <code>certctl rehash</code> on FreeBSD (needs root access).

=== Certificates ===
==== How to unseal when certificate have expired? ====
Use the web UI through SSH tunnel.

==== Renew Vault HTTP certificates ====

Vault uses TLS certificates managed by its own CA. That can create a chicken/egg issue if certificates have expired to connect to it, as the Vault client strictly requires valid TLS certificated to issue commands to renew certificates.

Connect to the web UI works as your browser is able to bypass certificate requirement. Opening a SSH tunnel with <code>-L 8200:complector:8200</code> should work for that.

Certificates configuration is available at [https://devcentral.nasqueron.org/D2639 D2639].

The web UI doesn't offer a comprehensive sets of widgets to generate certificates. You can instead use the ''Vault Browser CLI'' to run Vault CLI commands from the web UI. The signing operation can be done through endpoint configuration UI.

<div style="background-color: indianred; border: solid 3px black; color:white; font-size: large; padding: 2em;">Automation for this part is being tested.

You can preview automation proposal in /home/dereckson/sandbox/vault/renew-certificates on Complector.
</div>

Based on current D2639 state (2023-01), you can do the following:
* Has intermediate authority certificate expired? [old instructions, currently not valid anymore]
** Web console: <code>write -format=json pki_vault/intermediate/generate/internal common_name="nasqueron.drake Intermediate Authority"</code>
** At https://localhost:8200/ui/vault/secrets/pki_vault/pki/roles/nasqueron-drake you can use the sign intermediate button to sign it, don't forget to fill the following information:
*** CSR, pick from console the .data.csr output from JSON response
*** Format: pem_bundle
*** TTL: 100 days
*** Common name: "nasqueron.drake Intermediate Authority"
*** Organization: Nasqueron
*** Organization unit: Nasqueron Operations SIG
*** Country: BE
** Follow the warning instruction: copy the certificate bundle, and in pki_vault, use Set signed intermediate to set the certificate as intermediate one. That will create a new issuer, fetch the name in "issuers".
** Save also the certificate bundle to /usr/local/share/certs/nasqueron-vault-intermediate.crt
** Edit the nasqueron-drake role to use your new issuer name
* Has complector.nasqueron.drake certificate has expired?
** Web console: <code>write -format=json pki_vault/issue/nasqueron-drake common_name=complector.nasqueron.drake ttl=2160h ip_sans=127.0.0.1,172.27.27.7</code>, save the output in /usr/local/etc/certificates/vault files:
*** .data.certificate to certificate.pem
*** .data.issuing_ca to ca.pem
*** .data.private_key to private.key (careful how you replace the \n, if you use Python REPL, do it on Complector itself and get rid of the history with <code>import readline ; readline.clear_history()</code>)
** Prepare the fullchain bundle with <code>cat certificate.pem ca.pem > fullchain.pem</code>
** Send a SIGHUP signal to Vault to reload configuration with <code>kill -1 <Vault PID></code>, HTTP server should pick new certificate and you can know directly use the vault command. Vault configuration currently uses fullchain.pem and private.key.

CSR uses <code>line1\nline2\nline3</code> format in JSON. You can use a Python REPL with print("...") to print the CSR in several lines. CSR isn't confidential information, key is protected in Vault and never exposed.

'''jq.''' Another tool that can help is <code>jq</code>. For example, <code>cat certificate.json | jq -r .data.certificate > /usr/local/etc/certificates/vault/certificate.pem</code> will save it in multiline format.

If you get an issue about private key missing at Set signed intermediate step, don't forget you're setting an intermediate certificate for pki_vault, and not for pki_root, set that here: https://localhost:8200/ui/vault/settings/secrets/configure/pki_vault/cert

Paths where to store certificates matter:
* pki_root certificates are stored in /usr/local/share/certs
* pki_vault certificates are stored in /usr/local/etc/certificates/vault

Ensure `private.key` belongs to user `vault` and receives a correct chmod like 400.

==== Services known to break when a certificate is expired ====

* Salt, but that's ad-hoc and explicit
* Sentry containers: <code>sudo docker ps -a | grep sentry | grep -v "Up "</code>

=== Salt ===
==== Policy for a node doesn't contain new secret entry ====
If the policies are attached to a new role:

# Ensure new secret have been added for the right role in {{Ops file|pillar/credentials/vault.sls}}
#* If missing, validate afterwards with <code>salt complector pillar.get vault_secrets_by_role:yourrole</code>
#* You need to refresh the pillar if still missing: <code>salt complector saltutil.refresh_pillar</code>
# Ensure role has been added to {{Ops file|pillar/nodes/nodes.sls}} and NetBox
#* If missing, refresh pillar afterwards
#* Validate with <code>salt complector node.get roles <server name></code>
# Final check: <code>salt complector state.sls_id salt-node-<server name> roles/vault/policies test=True</code>
# If diff is complicated to read, check the full policies document by role: <code>salt complector credentials.build_policies_by_node</code>
#* Secret path present? Check the policy isn't already up-to-date: <code>vault policy read salt-node-<server name></code>

==== credentials.vault_policy_present returns Bad Request ====

Vault returns a 400 error if the policy format is incorrect.

'''Case 1.''' The state ID starts by <code>vault_policy_</code>. You manually added a file to roles/vault/policies/file: this error means Vault API founds a syntax error in it. You can use https://github.com/mschuchard/linter-vault-policy if you use Pulsar (ex Atom) to lint those files.

'''Case 2.''' The state ID starts by anything else. The policy has been generated through _modules/credentials.py.

Check if the pillar values added are correct:
* if not, add a test in <code>_tests/pillar/credentials/test_vault.py</code> to detect the case
* if yes, there is an issue with the Python module code to fix

'''Example of Salt output.'''

<syntaxhighlight>
----------
ID: vault_policy_admin
Function: credentials.vault_policy_present
Name: admin
Result: False
Comment: Failed to change policy: Bad Request
Started: 13:45:14.162421
Duration: 76.168 ms
Changes:
</syntaxhighlight>

[[Category:Operations grimoire]]
[[Category:Vault]]

Operations grimoire/Vault

2026-03-22T18:57:55Z

Dereckson: /* Get an admin-level token */

''This page currently documents Vault installed on complector as part of {{Ops file|roles/vault/}}. It doesn't document Docker or shellserver installation. See [[Operations grimoire/Eglide/Vault]] and [[Dev zone/Vault]].''

Hashicorp Vault allows to manage credentials and is currently used:

* to provision credentials through Salt
* to allow applications to fetch credentials
* to emit certificates for the private network applications
* to store credentials used by the Nasqueron Operations SIG beings

Vault policies are fully managed through Salt in the operations repository.

Vault has been selected in 2016 for secrets management.

== Vault reference ==
=== kv engine ===
The kv engine contains the following paths:

* ops/secrets: credentials like passwords, API tokens, private keys deployed to servers - a reference for machines
* ops/internal: credentials to third-party services internally shared amongst ops - a reference for humans
* ops/privacy: privacy information

==== Secrets ====
Secrets are directly and manually managed in Vault. If we need to run a disaster recovery procedure, we'll roll any secret by defining them again and deploy from rOPS those new secrets.

==== Privacy data ====
Personal identity information (PII) shared inside the Nasqueron Operations squad are more convenient to manage as a repository.

Such access to the repository is restricted to commit data, and ensure this data is deployed to the servers needing it. Any other use isn't allowed.

Information to the repository is then published in Vault, and referred in rOPS as Vault credentials.

'''Note:''' The ops/privacy path is only intended for PII of current or previous members of the Ops SIG, like IP addresses allowed to connect to restricted resources like the ops VPN. This is not acceptable to put 3rd party information in this repository.

=== pki engine ===
Services listening to private IPs use the Vault PKI to generate certificates:

* pki_root: root CA, certificate available at https://api.nasqueron.org/infra/security/pki/root/ca
* pki_vault: intermediate CA used for Vault itself

Certificates should be issued short-term and frequently renewed by automated services.

=== transit engine ===
Encryption as a service is available for applications under /transit path.

See https://learn.hashicorp.com/tutorials/vault/eaas-transit.

Applications should use a policy restricting to a subpath for that app, not to the whole engine.

=== Users accounts ===

Members of the Operations SIG need an access to Vault to create and maintain credentials.

Currently, we use tokens. To generate a token:

vault token create -policy=admin

To connect to Vault with a token from a devserver (e.g. WindRiver), you need:

# Store the token in <code>$HOME/.vault-token</code>
# Define environment variable VAULT_ADDR: <code>export VAULT_ADDR=https://172.27.27.7:8200</code>

Tokens need to be frequently renew (before expiration) with <code>vault renew</code>

== Salt configuration ==
=== Get a secret through Salt ===
The information in the ops/secrets and ops/privacy kv engines are integrated in the Salt pillar:

<syntaxhighlight lang="yaml">
ext_pillar:
# Credentials to deploy to servers
- vault:
conf: path=ops/secrets
nesting_key: credentials

# Personal identity information from Nasqueron Operations SIG members
- vault:
conf: path=ops/privacy
nesting_key: privacy
</syntaxhighlight>

You can then access to this information in Salt states using the following references:

{| class="wikitable"
|+ Access to Salt data
|-
! Category !! Example of path in Vault !! Example of pillar key in Salt
|-
| Secrets || ops/secrets/foo || pillar['credentials']['foo']
|-
| Privacy data || ops/privacy/ops-cidr || pillar['privacy']['ops-cidr']
|}

The ops/internal paths aren't accessible through Vault.

=== Policies ===

Policies are managed in {{Ops file|pillar/credentials/vault.sls}}.

For Salt, we deploy secrets to servers, policy management for a node consist to provide the list of secrets a role should have access to, generally in '''vault_secrets_by_role''' dictionary.

For other applications:
* create a policy .hcl in <code>roles/vault/policies/files/</code>
* declare the policy in the pillar under <code>vault_policies</code> list, it should match the .hcl file (without the extension or the path)
* run the repository tests to check if both information matches ; to only run that part, use <code>cd _tests && python3 -m unittest discover pillar/credentials/</code>

To add only an application policy, Salt can be deployed like this:

salt complector state.sls_id vault_policy_airflow roles/vault/policies

Salt policies can be tested by specifying the node name:

salt complector state.sls_id salt-node-windriver roles/vault/policies test=True

=== DRP ===
Any step we need to do to configure the engines should be added to the {{ops file|roles/vault/bootstrap}} unit.

If we need to recover Vault, two solutions are available:
* restore the storage, to keep data (credentials, certificates including the root CA one)
* recreate it from scratch through the roles/vault/bootstrap unit

== Howto ==
=== Allow a new application to authenticate to Vault ===
Applications need a policy and an authentication method, for example here for an application called yourservice with AppRole with secret_id and role_id:
# Create a new policy in operations repository: {{D|3270}}
# Deploy it from Complector with <code>salt complector state.sls_id vault_policy_yourservice roles/vault/policies</code>
# Create an approle matching that policy: <code>vault write auth/approle/role/yourservice token_policies="yourservice" token_ttl=1h token_max_ttl=4h</code>
# Get role_id with <code>vault read auth/approle/role/yourservice/role-id</code>
# Get secret_id with <code>vault write -force auth/approle/role/yourservice/secret-id</code>
# If you wish Salt to provision those credentials during your service deployment, probably a good idea to write them too: <code>vault kv put secrets/nasqueron/yourservice/vault username=role-id password=secret-id</code> [to skip if you don't use Salt to provision role-id and secret-id]

=== Get an admin-level token ===
Ops can use the self-service hvac script to get a token valid for 30 days:

ssh complector
cd /opt/salt/nasqueron-operations
sudo ./utils/vault/issue-admin-token.py

If Vault certificate has expired, add the `--insecure` argument.

You can also automate this as a oneliner to store the token in the default token file:

ssh complector sudo /opt/salt/nasqueron-operations/utils/vault/issue-admin-token.py > ~/.vault-token ; chmod 600 ~/.vault-token

== Troubleshoot ==
=== Connecting to Vault ===
==== Access to web UI ====
Vault isn't listening any public IP, but accept connections from internal network, so you can open a SSH tunnel against <code>complector:8200</code> and then browse https://localhost:8200:

<code>ssh -L 8200:complector:8200 router-001.nasqueron.org</code>

==== curl: (60) SSL certificate problem ====
Curl is compiled against a certificate bundle (<code>curl-config --ca</code> for the path). That bundle doesn't contain the pki_root certificate. We deploy this certificate in /etc/ssl/certs, but curl won't check there if not instructed to.

If you build an immutable environment like a container, add the certificate to the bundle.

On other machines, create a curl configuration file in ~/.curlrc (it doesn't seem currently possible to create a system one) with <code>capath=/etc/ssl/certs</code>.

If you've still the issue after that, check two things:
* with <code>curl -v</code>, the path should correctly there: <code>* CApath: /etc/ssl/certs</code> in addition to a CAfile.
* with <code>file /etc/ssl/certs/* | grep -i nasqueron</code> you should have a result ; if not, put the certificate in /usr/local/share/certs and relaunch the tool to link it in /etc/ssl/certs, for example <code>certctl rehash</code> on FreeBSD (needs root access).

=== Certificates ===
==== How to unseal when certificate have expired? ====
Use the web UI through SSH tunnel.

==== Renew Vault HTTP certificates ====

Vault uses TLS certificates managed by its own CA. That can create a chicken/egg issue if certificates have expired to connect to it, as the Vault client strictly requires valid TLS certificated to issue commands to renew certificates.

Connect to the web UI works as your browser is able to bypass certificate requirement. Opening a SSH tunnel with <code>-L 8200:complector:8200</code> should work for that.

Certificates configuration is available at [https://devcentral.nasqueron.org/D2639 D2639].

The web UI doesn't offer a comprehensive sets of widgets to generate certificates. You can instead use the ''Vault Browser CLI'' to run Vault CLI commands from the web UI. The signing operation can be done through endpoint configuration UI.

<div style="background-color: indianred; border: solid 3px black; color:white; font-size: large; padding: 2em;">Automation for this part is being tested.

You can preview automation proposal in /home/dereckson/sandbox/vault/renew-certificates on Complector.
</div>

Based on current D2639 state (2023-01), you can do the following:
* Has intermediate authority certificate expired? [old instructions, currently not valid anymore]
** Web console: <code>write -format=json pki_vault/intermediate/generate/internal common_name="nasqueron.drake Intermediate Authority"</code>
** At https://localhost:8200/ui/vault/secrets/pki_vault/pki/roles/nasqueron-drake you can use the sign intermediate button to sign it, don't forget to fill the following information:
*** CSR, pick from console the .data.csr output from JSON response
*** Format: pem_bundle
*** TTL: 100 days
*** Common name: "nasqueron.drake Intermediate Authority"
*** Organization: Nasqueron
*** Organization unit: Nasqueron Operations SIG
*** Country: BE
** Follow the warning instruction: copy the certificate bundle, and in pki_vault, use Set signed intermediate to set the certificate as intermediate one. That will create a new issuer, fetch the name in "issuers".
** Save also the certificate bundle to /usr/local/share/certs/nasqueron-vault-intermediate.crt
** Edit the nasqueron-drake role to use your new issuer name
* Has complector.nasqueron.drake certificate has expired?
** Web console: <code>write -format=json pki_vault/issue/nasqueron-drake common_name=complector.nasqueron.drake ttl=2160h ip_sans=127.0.0.1,172.27.27.7</code>, save the output in /usr/local/etc/certificates/vault files:
*** .data.certificate to certificate.pem
*** .data.issuing_ca to ca.pem
*** .data.private_key to private.key (careful how you replace the \n, if you use Python REPL, do it on Complector itself and get rid of the history with <code>import readline ; readline.clear_history()</code>)
** Prepare the fullchain bundle with <code>cat certificate.pem ca.pem > fullchain.pem</code>
** Send a SIGHUP signal to Vault to reload configuration with <code>kill -1 <Vault PID></code>, HTTP server should pick new certificate and you can know directly use the vault command. Vault configuration currently uses fullchain.pem and private.key.

CSR uses <code>line1\nline2\nline3</code> format in JSON. You can use a Python REPL with print("...") to print the CSR in several lines. CSR isn't confidential information, key is protected in Vault and never exposed.

'''jq.''' Another tool that can help is <code>jq</code>. For example, <code>cat certificate.json | jq -r .data.certificate > /usr/local/etc/certificates/vault/certificate.pem</code> will save it in multiline format.

If you get an issue about private key missing at Set signed intermediate step, don't forget you're setting an intermediate certificate for pki_vault, and not for pki_root, set that here: https://localhost:8200/ui/vault/settings/secrets/configure/pki_vault/cert

Paths where to store certificates matter:
* pki_root certificates are stored in /usr/local/share/certs
* pki_vault certificates are stored in /usr/local/etc/certificates/vault

Ensure `private.key` belongs to user `vault` and receives a correct chmod like 400.

==== Services known to break when a certificate is expired ====

* Salt, but that's ad-hoc and explicit
* Sentry containers: <code>sudo docker ps -a | grep sentry | grep -v "Up "</code>

=== Salt ===
==== Policy for a node doesn't contain new secret entry ====
If the policies are attached to a new role:

# Ensure new secret have been added for the right role in {{Ops file|pillar/credentials/vault.sls}}
#* If missing, validate afterwards with <code>salt complector pillar.get vault_secrets_by_role:yourrole</code>
#* You need to refresh the pillar if still missing: <code>salt complector saltutil.refresh_pillar</code>
# Ensure role has been added to {{Ops file|pillar/nodes/nodes.sls}} and NetBox
#* If missing, refresh pillar afterwards
#* Validate with <code>salt complector node.get roles <server name></code>
# Final check: <code>salt complector state.sls_id salt-node-<server name> roles/vault/policies test=True</code>
# If diff is complicated to read, check the full policies document by role: <code>salt complector credentials.build_policies_by_node</code>
#* Secret path present? Check the policy isn't already up-to-date: <code>vault policy read salt-node-<server name></code>

==== credentials.vault_policy_present returns Bad Request ====

Vault returns a 400 error if the policy format is incorrect.

'''Case 1.''' The state ID starts by <code>vault_policy_</code>. You manually added a file to roles/vault/policies/file: this error means Vault API founds a syntax error in it. You can use https://github.com/mschuchard/linter-vault-policy if you use Pulsar (ex Atom) to lint those files.

'''Case 2.''' The state ID starts by anything else. The policy has been generated through _modules/credentials.py.

Check if the pillar values added are correct:
* if not, add a test in <code>_tests/pillar/credentials/test_vault.py</code> to detect the case
* if yes, there is an issue with the Python module code to fix

'''Example of Salt output.'''

<syntaxhighlight>
----------
ID: vault_policy_admin
Function: credentials.vault_policy_present
Name: admin
Result: False
Comment: Failed to change policy: Bad Request
Started: 13:45:14.162421
Duration: 76.168 ms
Changes:
</syntaxhighlight>

[[Category:Operations grimoire]]
[[Category:Vault]]

Wearg

2026-03-21T09:48:02Z

Dereckson: /* MariaDB server connectivity */

Wearg is an eggdrop and a notifications client.

== Features ==

Wearg handles two important workflows for the Nasqueron Operations SIG:

* Publish notifications on IRC channels: Services --HTTPS--> [[Operations grimoire/Notifications center|Notifications center]] --AMQP--> [[Operations grimoire/RabbitMQ|broker]] --AMQP--> Wearg --IRC--> Channel publication
* Allow to log to servers log: Channel publication --HTTPS--> Nasqueron API --IO--> servers log

== Troubleshoot ==
=== No messages are received ===
Check through another client (the CLI client for example) all works fine at notifications center and broker level.

If so:

# Check we're connected through <code>.tcl mq connected</code>
# If so, disconnect it with <code>.tcl mq disconnect</code>
# Check timer through .tcl utimers, you should have one (and only one) timer with ::broker::on_tick as callback
## Too many timers? kill extra timers with <code>.tcl killutimer timer<id></code>, good luck for the guess the second game
## No timer? <code>.tcl broker::on_tick</code>
# Ask next message in the queue .tcl mq get wearg-notifications
# If stuck at the previous operation, close the connection through the broker interface: http://white-rabbit.nasqueron.org:15672/#/connections (username is daeghrefn, source IP is 212.83.187.132). This method is pretty effective

=== Can't publish to servers log ===
==== MariaDB server connectivity ====

If the MariaDB connection is broken, <code>.+log [server] message works</code>, but not directly <code>[server] message</code>.

* Short-term solution: <code>.tcl sqlrehash</code> in the Wearg partyline
* Long-term solution: automate reconnect with {{T|2282}}

Wearg

2026-03-21T09:47:30Z

Dereckson:

Wearg is an eggdrop and a notifications client.

== Features ==

Wearg handles two important workflows for the Nasqueron Operations SIG:

* Publish notifications on IRC channels: Services --HTTPS--> [[Operations grimoire/Notifications center|Notifications center]] --AMQP--> [[Operations grimoire/RabbitMQ|broker]] --AMQP--> Wearg --IRC--> Channel publication
* Allow to log to servers log: Channel publication --HTTPS--> Nasqueron API --IO--> servers log

== Troubleshoot ==
=== No messages are received ===
Check through another client (the CLI client for example) all works fine at notifications center and broker level.

If so:

# Check we're connected through <code>.tcl mq connected</code>
# If so, disconnect it with <code>.tcl mq disconnect</code>
# Check timer through .tcl utimers, you should have one (and only one) timer with ::broker::on_tick as callback
## Too many timers? kill extra timers with <code>.tcl killutimer timer<id></code>, good luck for the guess the second game
## No timer? <code>.tcl broker::on_tick</code>
# Ask next message in the queue .tcl mq get wearg-notifications
# If stuck at the previous operation, close the connection through the broker interface: http://white-rabbit.nasqueron.org:15672/#/connections (username is daeghrefn, source IP is 212.83.187.132). This method is pretty effective

=== Can't publish to servers log ===
==== MariaDB server connectivity ====

If the MariaDB connection is broken, <code>.+log [server] message works</code>, but not directly <code>[server] message</code>.

Short-term solution: <code>.tcl sqlrehash</code> in the Wearg partyline
Long-term solution: {{T|2282}}

Code conventions

2026-03-20T01:47:16Z

Dereckson: /* Makefile */

== All languages ==

* Don't use more complicated constructs like ternary operators
* [http://jeroendedauw.github.io/slides/craftmanship/functions/#/1 Keep functions short and simple].
* Define explicitly methods visibility, as several languages have different default values (e.g. private for C# class members, public for PHP methods)
* Comments to document a method are written at the singular 3rd person (we seem to have moved to infinitive recently, we need to take a decision here)

== C ==
If you use [http://clang.llvm.org/docs/ClangFormat.html ClangFormat], a [https://github.com/dereckson/rabbitmq-tcl/blob/master/.clang-format .clang-format file] is available.

== JavaScript ==
The following conventions are used:
* K&R, 1TBS variant, including for functions
* 4 spaces as indent
* Use modern JavaScript idioms like <code>const</code> and <code>let</code> instead of <code>var</code>
* Consider to use async code for events-driven development, especially for servers

== PHP ==
The following conventions are used:
* K&R, 1TBS variant, including for functions
* 4 spaces as indent
* The keywords <code>true</code>, <code>false</code> and <code>null</code> must be in lower case.
* Arrays use short syntax
* Array elements ends with a comma
* Functions, methods and class names use camel case

If you use PhpStorm or another JetBrains IDE, you can import [https://github.com/nasqueron/codestyle/blob/master/JetBrains/php-codestyle.xml JetBrains/php-codestyle.xml] from the codestyle repository as a code style (Settings or Default Settings > Editor > Code Style > PHP > click on the wheel icon > Import Scheme > Intellij IDEA codestyle XML).

If you want to lint a project with phpcs, you can require the Composer package <code>nasqueron/codestyle</code> and use the following <kbd>phpcs.xml<kbd> standard file:

<syntaxhighlight lang="xml">
<?xml version="1.0"?>
<ruleset>
<rule ref="vendor/nasqueron/codestyle/CodeSniffer" />
<file>.</file>
<exclude-pattern>\.git/</exclude-pattern>
<exclude-pattern>vendor/</exclude-pattern>
</ruleset>
</syntaxhighlight>

== Python ==
=== Code style ===
'''2023.''' We follow [https://black.readthedocs.io/en/stable/the_black_code_style/current_style.html black style], so use black utility (<code>pip install black</code>). As such, you need to configure Flake8 to ignore rule E203.

'''2015.''' We follow [https://www.python.org/dev/peps/pep-0008/ PEP-8].

=== Templates ===
A template exists for a new Python command: [https://devcentral.nasqueron.org/source/snippets/browse/main/python/command.py python/command.py]

In packages, empty __init__.py files can follow [https://devcentral.nasqueron.org/source/merge-dictionaries/browse/main/src/mergedictionaries/utils/__init__.py;eaf5bc2c21118454837e8148147606c19d4afff7 this example].

=== Configuration files ===
Allow empty configuration files. For example, the YAML parser will return None if the file exists but is empty, we can catch that and return default instead:

<syntaxhighlight lang="python">
with open(get_configuration_path()) as fd:
return yaml.safe_load(fd) or {}
</syntaxhighlight>

== Rust ==
'''2023.''' Automated codestyle (black in Python, clang-format in Rust) seems preferable. As such, a style compatible with <code>rustfmt</code> is needed to be able to format using <code>cargo fmt</code>. You can add to your project [https://devcentral.nasqueron.org/source/codestyle/browse/main/rust/rustfmt.toml rust/rustfmt.toml in codestyle] to configure it.

'''2015.''' We followed "Rust default style", described at [https://web.archive.org/web/20170320083740/http://aturon.github.io/ https://aturon.github.io/]. It's mainly a K&R, 1TBS variant.

Use trailing comma for elements in every struct/impl/etc.

=== Threads ===
Standard library isn't the most ergonomic for threads programming, those crate allows more efficient and legible code:
* [https://docs.rs/crossbeam-channel/latest/crossbeam_channel/ crossbeam_channel] for mpmc (multiple producers, multiple consumers)
* [https://docs.rs/parking_lot/latest/parking_lot/type.Mutex.html parking_lot] for Mutex

== Salt ==
=== Style ===
Whitespaces:
* Indent with two spaces
* YAML lists use indented bullets

<syntaxhighlight lang="yaml">
id:
method:
- somekey: value
- otherkey: value
</syntaxhighlight>

=== Tips ===

;Files provisioned
* When you ask to download a file remotely, you need a source hash, pick SHA256 as algo
* Each file provisioned from the Salt repository must contains an header explaining the fact, with the full path in the rOPS repo

;BSD and Linux distros compatible states
* populate the map.jinja file with OS logic (e.g. `dirs` for /etc vs /usr/local/etc)
* when you've a specific set of tasks to do for one OS/distro, it's acceptable to enclose it in a state by an if block

=== Vocabulary ===

;Domain names
:To refer to the fully qualified domain name sub.domain.tld, use '''fqdn'''. To split the domains in part, use '''domain''' and '''subdomain'''. This is important to understand a state without having to refer to the associated pillar to disambig domain.

== Shell scripts ==
;UNIX agnosticism:
* Don't assume absolute path, use <code>#!/usr/bin/env bash</code> and not <code>#!/bin/bash</code> (it could be elsewhere on BSD or Solaris)
* Use `sh` as must as possible, try to avoid <code>bash</code>, document exceptions rationale in your commits

;Whitespaces:
* One whitespace line between shebang and actual content
* 4 spaces as indent

;File names:
* We use hyphens (-) as separators, not underscores or camelcase
* Filename should start by a verb if it performs an action
* Don't use .sh extensions when deployed as command
** sometimes you'll see them on Phabricator pastes' titles, but it has been added there, so Phab knows shell syntax highlighting should be used
** '''Tip.''' You can use .sh in src/ to help linters, but then provide a Makefile to install it under correct name without extension. Same for operations repository where everything uses .sh, but when deploying with file.managed the extension is omitted

;Templates
* New command: [https://devcentral.nasqueron.org/source/snippets/browse/main/shell/script.sh shell/script.sh]

== TCL ==

* Indent with 4 spaces, as of 2026-03-20
* Keep blocks visually separated
* Use Tcl primitives instead of manual parsing for strings: split, lindex, lrange, join
* Avoid regex unless necessary
* List expansion {*} instead of eval

; ViperServ development
* If you build a full new system, all procedures must be defined in a namespace
* Use fully-qualified names (::namespace::proc) for procedure definitions and cross-namespace calls
* Separate low-level request logic from API-specific methods

== Makefile ==
UNIX agnosticism:
* Test your makefile against BSD make, and document in README.md to use GNU Makefile (gmake) when it's not convenient to keep compatibility

Presentation:
* Create a block with the general targets, then sections with your targets organized by categories/goals/parts

Tip:
* It's possible to provision BSDmakefile and GNUmakefile when UNIX agnosticism doesn't work.

== Structured data formats (YAML, JSON, XML) ==
The number of spaces depend if the format is usually heavily hierarchized or not:

* 2 spaces for JSON and YAML
* 4 spaces for XML, TOML and other configuration files

== Utilities ==

The https://github.com/nasqueron/codestyle repository contains resource to help to respect code convention, like a phpcs ruleset, a configuration ready for PhpStorm, IntelliJ and other JetBrains editors, or a clang-format configuration file.

== Troubleshoot ==
=== Fix indent issues ===
The <code>expand</code> utility converts tabs into spaces, while <code>unexpand</code> convert spaces into tabs.

Switch a file from tab indent to 4 spaces indent:

$ expand -t 4 foo.sh > a
$ cat a > foo.sh
$ rm a

(Avoid <code>mv</code> for shell scripts as your foo.sh has probably a 755 chmod, and a will probably have a 644 chmod, assuming 022 as umask)

Switch a file indent with 2 spaces to 4 spaces:

$ unexpand -t 2 JetBrains/php-codestyle.xml > a
$ expand -t 4 a > JetBrains/php-codestyle.xml

This last technique can be used in batch [https://gist.github.com/dereckson/80a746b408c0cf0b688a09db31d5c881 with this reindent script]:

$ git ls-files | xargs -n1 reindent 2 4

[[Category:Reference]]
[[Category:Contributor guide]]

Clean up

2026-03-20T01:38:43Z

Dereckson: /* Tab to spaces */

== Style ==
=== EOL at EOF ===
There is a need for a blank line at end of file.

You can add them with <code>echo</code>.

<syntaxhighlight lang="console">
$ git ls-files | while read f; do tail -n1 $f | read -r _ || echo >> $f; done
</syntaxhighlight>

=== UNIX lines ===
<syntaxhighlight lang="console">
$ dos2unix
</syntaxhighlight>

=== Encoding ===
<syntaxhighlight lang="console">
$ iconv -f iso-8859-15 -t utf-8
</syntaxhighlight>

=== Tab to spaces ===
Git has a filter to be able to normalize with expand. See [https://eev.ee/blog/2016/06/04/converting-a-git-repo-from-tabs-to-spaces/ here].

As expand doesn't have a inline capability, you need to create a temporary file:

tmp_file=$(mktemp -t spaces)
expand -t 4 "$source_file" > "$tmp_file"
mv "$tmp_file" "$source_file"

=== Trailing spaces ===
<syntaxhighlight lang="console">
$ git ls-files | xargs -n 1 gsed -i 's/[[:space:]]*$//'
</syntaxhighlight>

=== UTF-8 BOM ===
Some old editors started a file by the sequence of bytes [0xEF, 0xBB, 0xBF] to allow the UTF-8 file encoding to be detected. This practice is discouraged nowadays and those should removed.

<syntaxhighlight lang="console">
$ sed -e '1s/^\xef\xbb\xbf//' < bomfile > newfile
</syntaxhighlight>

[[Category:Howto]]
[[Category:Contributor guide]]

WindRiver

2026-03-19T22:23:05Z

Dereckson:

User:Dereckson/Devserver

2026-03-19T22:02:12Z

Dereckson:

== MediaWiki ==
=== Logs ===
tail -n 100 -f /var/log/www/dereckson.be/mediawiki-php.log

=== Reinstall ===
* /var/51-wwwroot/mediawiki-dereckson/core: wikimedia/core repository
* /var/51-wwwroot/mediawiki-dereckson/core/extensions: symlink to <code>../extensions</code>
** Clone all needed extensions in /var/51-wwwroot/mediawiki-dereckson/extensions
* /var/51-wwwroot/mediawiki-dereckson/core/skins: symlink to <code>../skins</code>
** Same with git clone ssh://review/mediawiki/skins/
* /var/dataroot/mediawiki.dereckson.be/data contains:
** my_wiki.sqlite for the content
** wikicache.sqlite for the cache

=== Update ===
* '''Core:''' mw-update-core (currently writing it)

=== Create a new extension ===
;I. Wikimedia side
* [[mw:Manual:Developing_extensions]]
* [[mw:Gerrit/New repositories/Requests]]
* [https://phabricator.wikimedia.org/maniphest/task/edit/form/1/?projects=Project-Admins Create task for new Phabricator project]

;II. WindRiver

<syntaxhighlight lang="shell">
$ setenv MW_EXTENSION foo
$ cd ~/dev/wikimedia/mediawiki/extensions
$ git clone ssh://review/mediawiki/extensions/$MW_EXTENSION || git init $MW_EXTENSION
</syntaxhighlight>

Extension is actually stored at /var/51-wwwroot/mediawiki-dereckson/extensions, so can immediately be configured to test locally.

;III. SaaS deployment
* {{Ops file|pillar/saas/mediawiki.sls}}
* [https://devcentral.nasqueron.org/source/saas-mediawiki/browse/main/config/Settings.php config/Settings.php]

=== Troubleshoot ===
==== SQLite database is read-only ====
Runtime error near line 2: attempt to write a readonly database (8)

<syntaxhighlight lang="shell">
chown -R web-be-dereckson-mw:dereckson /var/dataroot/mediawiki.dereckson.be/data
chmod 771 /var/dataroot/mediawiki.dereckson.be/data
chmod 660 /var/dataroot/mediawiki.dereckson.be/data/my_wiki.sqlite
</syntaxhighlight>

=== Permissions to run tests and maintenance scripts ===
To run tests against wiki and maintenance scripts as user can be tricky:

<syntaxhighlight lang="shell">
touch /tmp/mw-GlobalIdGenerator5001-UID-nodeid /tmp/mw-GlobalIdGenerator5001-UUID-128
chown web-be-dereckson-mw:dereckson /tmp/mw-GlobalIdGenerator5001-*
chmod 664 /tmp/mw-GlobalIdGenerator5001-*

chmod 771 /var/dataroot/mediawiki.dereckson.be/data/locks
</syntaxhighlight>

== Zed ==
=== Logs ===
tail -n 100 -f /var/log/www/dereckson.be/zed51-php.log

=== Staging ===

'''Note. Keruald is currently symlinked from the monorepo to vendor/keruald.'''

To recreate Zed staging area:

$ cd /var/dataroot/zed/content
$ git init .
$ git config --global --add safe.directory /var/dataroot/zed/content
$ git remote add origin git@github.com:hypership/content.git
$ git fetch --all
$ git reset --hard origin/main
$ git clone git@github.com:hypership/content_users.git users

$ sudo -u web-be-dereckson-zed51 mkdir /var/dataroot/zed/cache/sessions
$ sudo mkdir -p /var/dataroot/zed/content/users/_photos/tn
$ sudo chown -R web-be-dereckson-zed51:dereckson /var/dataroot/zed/content/users/_photos
$ sudo chmod 771 /var/dataroot/zed/content/users/_photos /var/dataroot/zed/content/users/_photos/tn

$ mkdir -p /home/dereckson/dev/zed/hypership
$ cd /home/dereckson/dev/zed/hypership
$ ln -s /var/dataroot/zed/content

Note: Zed currently not defined in wwwroot-51 in rOPS, should be done for /var/51-wwwroot/zed

== IRC ==

=== Troubleshoot ===
==== Error loading module proxy/irc ====
When trying to load proxy module, I got:

22:00:09 -!- Irssi: Error loading module proxy/irc: /home/dereckson/.irssi/modules/libirc_proxy.so: Undefined symbol "g_input_add"

Proxy is now compiled by default, personal module needs to be deleted.

Clean up

2026-03-09T14:00:51Z

Dereckson:

== Style ==
=== EOL at EOF ===
There is a need for a blank line at end of file.

You can add them with <code>echo</code>.

<syntaxhighlight lang="console">
$ git ls-files | while read f; do tail -n1 $f | read -r _ || echo >> $f; done
</syntaxhighlight>

=== UNIX lines ===
<syntaxhighlight lang="console">
$ dos2unix
</syntaxhighlight>

=== Encoding ===
<syntaxhighlight lang="console">
$ iconv -f iso-8859-15 -t utf-8
</syntaxhighlight>

=== Tab to spaces ===
Git has a filter to be able to normalize with expand. See [https://eev.ee/blog/2016/06/04/converting-a-git-repo-from-tabs-to-spaces/ here].

=== Trailing spaces ===
<syntaxhighlight lang="console">
$ git ls-files | xargs -n 1 gsed -i 's/[[:space:]]*$//'
</syntaxhighlight>

=== UTF-8 BOM ===
Some old editors started a file by the sequence of bytes [0xEF, 0xBB, 0xBF] to allow the UTF-8 file encoding to be detected. This practice is discouraged nowadays and those should removed.

<syntaxhighlight lang="console">
$ sed -e '1s/^\xef\xbb\xbf//' < bomfile > newfile
</syntaxhighlight>

[[Category:Howto]]
[[Category:Contributor guide]]

Clean up

2026-03-09T13:19:44Z

Dereckson: +trailing spaces

== Style ==
=== EOL at EOF ===
There is a need for a blank line at end of file.

You can add them with <code>echo</code>.

<syntaxhighlight lang="console">
$ git ls-files | while read f; do tail -n1 $f | read -r _ || echo >> $f; done
</syntaxhighlight>

=== UNIX lines ===
<syntaxhighlight lang="console">
$ dos2unix
</syntaxhighlight>

=== Encoding ===
<syntaxhighlight lang="console">
$ iconv -f iso-8859-15 -t utf-8
</syntaxhighlight>

=== Tab to spaces ===
Git has a filter to be able to normalize with expand. See [https://eev.ee/blog/2016/06/04/converting-a-git-repo-from-tabs-to-spaces/ here].

== Trailing spaces ==
<syntaxhighlight lang="console">
$ git ls-files | xargs -n 1 gsed -i 's/[[:space:]]*$//'
</syntaxhighlight>

=== UTF-8 BOM ===
Some old editors started a file by the sequence of bytes [0xEF, 0xBB, 0xBF] to allow the UTF-8 file encoding to be detected. This practice is discouraged nowadays and those should removed.

<syntaxhighlight lang="console">
$ sed -e '1s/^\xef\xbb\xbf//' < bomfile > newfile
</syntaxhighlight>

[[Category:Howto]]
[[Category:Contributor guide]]

Operations grimoire/Vault

2026-03-02T18:00:24Z

Dereckson: /* Policies */

''This page currently documents Vault installed on complector as part of {{Ops file|roles/vault/}}. It doesn't document Docker or shellserver installation. See [[Operations grimoire/Eglide/Vault]] and [[Dev zone/Vault]].''

Hashicorp Vault allows to manage credentials and is currently used:

* to provision credentials through Salt
* to allow applications to fetch credentials
* to emit certificates for the private network applications
* to store credentials used by the Nasqueron Operations SIG beings

Vault policies are fully managed through Salt in the operations repository.

Vault has been selected in 2016 for secrets management.

== Vault reference ==
=== kv engine ===
The kv engine contains the following paths:

* ops/secrets: credentials like passwords, API tokens, private keys deployed to servers - a reference for machines
* ops/internal: credentials to third-party services internally shared amongst ops - a reference for humans
* ops/privacy: privacy information

==== Secrets ====
Secrets are directly and manually managed in Vault. If we need to run a disaster recovery procedure, we'll roll any secret by defining them again and deploy from rOPS those new secrets.

==== Privacy data ====
Personal identity information (PII) shared inside the Nasqueron Operations squad are more convenient to manage as a repository.

Such access to the repository is restricted to commit data, and ensure this data is deployed to the servers needing it. Any other use isn't allowed.

Information to the repository is then published in Vault, and referred in rOPS as Vault credentials.

'''Note:''' The ops/privacy path is only intended for PII of current or previous members of the Ops SIG, like IP addresses allowed to connect to restricted resources like the ops VPN. This is not acceptable to put 3rd party information in this repository.

=== pki engine ===
Services listening to private IPs use the Vault PKI to generate certificates:

* pki_root: root CA, certificate available at https://api.nasqueron.org/infra/security/pki/root/ca
* pki_vault: intermediate CA used for Vault itself

Certificates should be issued short-term and frequently renewed by automated services.

=== transit engine ===
Encryption as a service is available for applications under /transit path.

See https://learn.hashicorp.com/tutorials/vault/eaas-transit.

Applications should use a policy restricting to a subpath for that app, not to the whole engine.

=== Users accounts ===

Members of the Operations SIG need an access to Vault to create and maintain credentials.

Currently, we use tokens. To generate a token:

vault token create -policy=admin

To connect to Vault with a token from a devserver (e.g. WindRiver), you need:

# Store the token in <code>$HOME/.vault-token</code>
# Define environment variable VAULT_ADDR: <code>export VAULT_ADDR=https://172.27.27.7:8200</code>

Tokens need to be frequently renew (before expiration) with <code>vault renew</code>

== Salt configuration ==
=== Get a secret through Salt ===
The information in the ops/secrets and ops/privacy kv engines are integrated in the Salt pillar:

<syntaxhighlight lang="yaml">
ext_pillar:
# Credentials to deploy to servers
- vault:
conf: path=ops/secrets
nesting_key: credentials

# Personal identity information from Nasqueron Operations SIG members
- vault:
conf: path=ops/privacy
nesting_key: privacy
</syntaxhighlight>

You can then access to this information in Salt states using the following references:

{| class="wikitable"
|+ Access to Salt data
|-
! Category !! Example of path in Vault !! Example of pillar key in Salt
|-
| Secrets || ops/secrets/foo || pillar['credentials']['foo']
|-
| Privacy data || ops/privacy/ops-cidr || pillar['privacy']['ops-cidr']
|}

The ops/internal paths aren't accessible through Vault.

=== Policies ===

Policies are managed in {{Ops file|pillar/credentials/vault.sls}}.

For Salt, we deploy secrets to servers, policy management for a node consist to provide the list of secrets a role should have access to, generally in '''vault_secrets_by_role''' dictionary.

For other applications:
* create a policy .hcl in <code>roles/vault/policies/files/</code>
* declare the policy in the pillar under <code>vault_policies</code> list, it should match the .hcl file (without the extension or the path)
* run the repository tests to check if both information matches ; to only run that part, use <code>cd _tests && python3 -m unittest discover pillar/credentials/</code>

To add only an application policy, Salt can be deployed like this:

salt complector state.sls_id vault_policy_airflow roles/vault/policies

Salt policies can be tested by specifying the node name:

salt complector state.sls_id salt-node-windriver roles/vault/policies test=True

=== DRP ===
Any step we need to do to configure the engines should be added to the {{ops file|roles/vault/bootstrap}} unit.

If we need to recover Vault, two solutions are available:
* restore the storage, to keep data (credentials, certificates including the root CA one)
* recreate it from scratch through the roles/vault/bootstrap unit

== Howto ==
=== Allow a new application to authenticate to Vault ===
Applications need a policy and an authentication method, for example here for an application called yourservice with AppRole with secret_id and role_id:
# Create a new policy in operations repository: {{D|3270}}
# Deploy it from Complector with <code>salt complector state.sls_id vault_policy_yourservice roles/vault/policies</code>
# Create an approle matching that policy: <code>vault write auth/approle/role/yourservice token_policies="yourservice" token_ttl=1h token_max_ttl=4h</code>
# Get role_id with <code>vault read auth/approle/role/yourservice/role-id</code>
# Get secret_id with <code>vault write -force auth/approle/role/yourservice/secret-id</code>
# If you wish Salt to provision those credentials during your service deployment, probably a good idea to write them too: <code>vault kv put secrets/nasqueron/yourservice/vault username=role-id password=secret-id</code> [to skip if you don't use Salt to provision role-id and secret-id]

=== Get an admin-level token ===
Ops can use the self-service hvac script to get a token valid for 30 days:

ssh complector
cd /opt/salt/nasqueron-operations
sudo ./utils/vault/issue-admin-token.py

If Vault certificate has expired, add the `--insecure` argument.

== Troubleshoot ==
=== Connecting to Vault ===
==== Access to web UI ====
Vault isn't listening any public IP, but accept connections from internal network, so you can open a SSH tunnel against <code>complector:8200</code> and then browse https://localhost:8200:

<code>ssh -L 8200:complector:8200 router-001.nasqueron.org</code>

==== curl: (60) SSL certificate problem ====
Curl is compiled against a certificate bundle (<code>curl-config --ca</code> for the path). That bundle doesn't contain the pki_root certificate. We deploy this certificate in /etc/ssl/certs, but curl won't check there if not instructed to.

If you build an immutable environment like a container, add the certificate to the bundle.

On other machines, create a curl configuration file in ~/.curlrc (it doesn't seem currently possible to create a system one) with <code>capath=/etc/ssl/certs</code>.

If you've still the issue after that, check two things:
* with <code>curl -v</code>, the path should correctly there: <code>* CApath: /etc/ssl/certs</code> in addition to a CAfile.
* with <code>file /etc/ssl/certs/* | grep -i nasqueron</code> you should have a result ; if not, put the certificate in /usr/local/share/certs and relaunch the tool to link it in /etc/ssl/certs, for example <code>certctl rehash</code> on FreeBSD (needs root access).

=== Certificates ===
==== How to unseal when certificate have expired? ====
Use the web UI through SSH tunnel.

==== Renew Vault HTTP certificates ====

Vault uses TLS certificates managed by its own CA. That can create a chicken/egg issue if certificates have expired to connect to it, as the Vault client strictly requires valid TLS certificated to issue commands to renew certificates.

Connect to the web UI works as your browser is able to bypass certificate requirement. Opening a SSH tunnel with <code>-L 8200:complector:8200</code> should work for that.

Certificates configuration is available at [https://devcentral.nasqueron.org/D2639 D2639].

The web UI doesn't offer a comprehensive sets of widgets to generate certificates. You can instead use the ''Vault Browser CLI'' to run Vault CLI commands from the web UI. The signing operation can be done through endpoint configuration UI.

<div style="background-color: indianred; border: solid 3px black; color:white; font-size: large; padding: 2em;">Automation for this part is being tested.

You can preview automation proposal in /home/dereckson/sandbox/vault/renew-certificates on Complector.
</div>

Based on current D2639 state (2023-01), you can do the following:
* Has intermediate authority certificate expired? [old instructions, currently not valid anymore]
** Web console: <code>write -format=json pki_vault/intermediate/generate/internal common_name="nasqueron.drake Intermediate Authority"</code>
** At https://localhost:8200/ui/vault/secrets/pki_vault/pki/roles/nasqueron-drake you can use the sign intermediate button to sign it, don't forget to fill the following information:
*** CSR, pick from console the .data.csr output from JSON response
*** Format: pem_bundle
*** TTL: 100 days
*** Common name: "nasqueron.drake Intermediate Authority"
*** Organization: Nasqueron
*** Organization unit: Nasqueron Operations SIG
*** Country: BE
** Follow the warning instruction: copy the certificate bundle, and in pki_vault, use Set signed intermediate to set the certificate as intermediate one. That will create a new issuer, fetch the name in "issuers".
** Save also the certificate bundle to /usr/local/share/certs/nasqueron-vault-intermediate.crt
** Edit the nasqueron-drake role to use your new issuer name
* Has complector.nasqueron.drake certificate has expired?
** Web console: <code>write -format=json pki_vault/issue/nasqueron-drake common_name=complector.nasqueron.drake ttl=2160h ip_sans=127.0.0.1,172.27.27.7</code>, save the output in /usr/local/etc/certificates/vault files:
*** .data.certificate to certificate.pem
*** .data.issuing_ca to ca.pem
*** .data.private_key to private.key (careful how you replace the \n, if you use Python REPL, do it on Complector itself and get rid of the history with <code>import readline ; readline.clear_history()</code>)
** Prepare the fullchain bundle with <code>cat certificate.pem ca.pem > fullchain.pem</code>
** Send a SIGHUP signal to Vault to reload configuration with <code>kill -1 <Vault PID></code>, HTTP server should pick new certificate and you can know directly use the vault command. Vault configuration currently uses fullchain.pem and private.key.

CSR uses <code>line1\nline2\nline3</code> format in JSON. You can use a Python REPL with print("...") to print the CSR in several lines. CSR isn't confidential information, key is protected in Vault and never exposed.

'''jq.''' Another tool that can help is <code>jq</code>. For example, <code>cat certificate.json | jq -r .data.certificate > /usr/local/etc/certificates/vault/certificate.pem</code> will save it in multiline format.

If you get an issue about private key missing at Set signed intermediate step, don't forget you're setting an intermediate certificate for pki_vault, and not for pki_root, set that here: https://localhost:8200/ui/vault/settings/secrets/configure/pki_vault/cert

Paths where to store certificates matter:
* pki_root certificates are stored in /usr/local/share/certs
* pki_vault certificates are stored in /usr/local/etc/certificates/vault

Ensure `private.key` belongs to user `vault` and receives a correct chmod like 400.

==== Services known to break when a certificate is expired ====

* Salt, but that's ad-hoc and explicit
* Sentry containers: <code>sudo docker ps -a | grep sentry | grep -v "Up "</code>

=== Salt ===
==== Policy for a node doesn't contain new secret entry ====
If the policies are attached to a new role:

# Ensure new secret have been added for the right role in {{Ops file|pillar/credentials/vault.sls}}
#* If missing, validate afterwards with <code>salt complector pillar.get vault_secrets_by_role:yourrole</code>
#* You need to refresh the pillar if still missing: <code>salt complector saltutil.refresh_pillar</code>
# Ensure role has been added to {{Ops file|pillar/nodes/nodes.sls}} and NetBox
#* If missing, refresh pillar afterwards
#* Validate with <code>salt complector node.get roles <server name></code>
# Final check: <code>salt complector state.sls_id salt-node-<server name> roles/vault/policies test=True</code>
# If diff is complicated to read, check the full policies document by role: <code>salt complector credentials.build_policies_by_node</code>
#* Secret path present? Check the policy isn't already up-to-date: <code>vault policy read salt-node-<server name></code>

==== credentials.vault_policy_present returns Bad Request ====

Vault returns a 400 error if the policy format is incorrect.

'''Case 1.''' The state ID starts by <code>vault_policy_</code>. You manually added a file to roles/vault/policies/file: this error means Vault API founds a syntax error in it. You can use https://github.com/mschuchard/linter-vault-policy if you use Pulsar (ex Atom) to lint those files.

'''Case 2.''' The state ID starts by anything else. The policy has been generated through _modules/credentials.py.

Check if the pillar values added are correct:
* if not, add a test in <code>_tests/pillar/credentials/test_vault.py</code> to detect the case
* if yes, there is an issue with the Python module code to fix

'''Example of Salt output.'''

<syntaxhighlight>
----------
ID: vault_policy_admin
Function: credentials.vault_policy_present
Name: admin
Result: False
Comment: Failed to change policy: Bad Request
Started: 13:45:14.162421
Duration: 76.168 ms
Changes:
</syntaxhighlight>

[[Category:Operations grimoire]]
[[Category:Vault]]

Internship guide/Best practices for mentors

2026-02-21T15:32:24Z

Dereckson: /* Rules we'd like to follow in the future */

== Context and experience ==

Nasqueron is a small-size open-source project and free culture community. When we offer an internship, the outcome is really different based on the motivation and the level of the intern.

Our experience is based on 7 internships offered and it's only the second year we offer such a program, so the experience is based on a small dataset.

The ideal intern is:
* self-directed
* motivated
* able to engage with the mentor

Remote / non-remote balance doesn't seem to matter — we had a lukewarm experience with an intern on-site and a stellar experience with a remote intern with big timezone difference. Our workflows allow remote connection.

Communication tools matter: we had good experiences with IRC and WhatsApp communication, mixed results on DevCentral integrated chat; we would like to experience what's going on with solutions like Mattermost/Zulip/Stoat/Slack/Discord.

The mentor seems to matter too:
* Dorian and Dereckson looks hard to win — you need to be a good to very good contributor to gain their approval, either technically or with eagerness to learn.
* Eli is clearly more open to help a newcomer to find their first steps and takes care not to overwhelm them.

== Rules we'd like to follow in the future ==
* '''Backup.''' We really need to have a backup mentor for each internship.
* '''Remote or hybrid.''' A minimal number of days on-site isn't acceptable.
* '''Experience.''' Projects engagement show we can provide a really more meaningful internship for experienced students.
* '''Favour ops/security/network track.''' Internships in non-dev is rather hard to find, and Nasqueron tasks seem really infrastructure-oriented, so we can provide real projects, experience, knowledge and culture. That works and that works well (80% success), so that's we clearly bring something on the table here and an opportunity for interns to grow. For developers, it seems more complicated: our practices and infrastructure are clearly tailored for developers at ease with complicated tooling and workflows, and our project doesn't seem fit for newcomers, whatever we try — something also noticed on Wikimedia programs, where a lot of things were tried to improve engagement and success.
* '''Initial engagement.''' Ideally, tooling training (arc/git workflow) should be offered beforehand. We should offer a small task to complete in that goal.
* '''Communication.''' Continuous communication must occur: we need interns able to initiate the communication from their side too when needed, and with a backup mentor, both can also ensure communications from our side work well too.

== Relations with education organisations ==

In Belgium, there are two kind of internships:
* through IFAPME — really bureaucratic, but they seem to want to adapt to organisations needs
* from superior schools and universities — either they don't care, either they clearly consider they can impose the rules

From France, we had problems with cases of on-site requirements during COVID-19 lockdowns.

Requirements from the school need to be taken in consideration:
* what's the obligation of the mentor?
* jury participation? lot of documents to fill?
* is hybrid work acceptable?

Experience shows we need in the future to refuse interns from schools with on-site requirements.

Internship guide/Best practices for mentors

2026-02-21T15:32:11Z

Dereckson: /* Rules we'd like to follow in the future */

== Context and experience ==

Nasqueron is a small-size open-source project and free culture community. When we offer an internship, the outcome is really different based on the motivation and the level of the intern.

Our experience is based on 7 internships offered and it's only the second year we offer such a program, so the experience is based on a small dataset.

The ideal intern is:
* self-directed
* motivated
* able to engage with the mentor

Remote / non-remote balance doesn't seem to matter — we had a lukewarm experience with an intern on-site and a stellar experience with a remote intern with big timezone difference. Our workflows allow remote connection.

Communication tools matter: we had good experiences with IRC and WhatsApp communication, mixed results on DevCentral integrated chat; we would like to experience what's going on with solutions like Mattermost/Zulip/Stoat/Slack/Discord.

The mentor seems to matter too:
* Dorian and Dereckson looks hard to win — you need to be a good to very good contributor to gain their approval, either technically or with eagerness to learn.
* Eli is clearly more open to help a newcomer to find their first steps and takes care not to overwhelm them.

== Rules we'd like to follow in the future ==
* '''Backup.''' We really need to have a backup mentor for each internship.
* '''Remote or hybrid.''' A minimal number of days on-site isn't acceptable.
* '''Experience.''' Projects engagement show we can provide a really more meaningful internship for experienced students.
* '''Favour ops/security/network track.''' Internships in non-dev is rather hard to find, and Nasqueron tasks seem really infrastructure-oriented, so we can provide real projects, experience, knowledge and culture. That works and that works well (80% success), so that's we clearly bring something on the table here and an opportunity for interns to grow. For developers, it seems more complicated: our practices and infrastructure are clearly tailored for developers at ease with complicated tooling and workflows, and our project doesn't seem fit for newcomers, whatever we try — something also noticed on Wikimedia programs.
* '''Initial engagement.''' Ideally, tooling training (arc/git workflow) should be offered beforehand. We should offer a small task to complete in that goal.
* '''Communication.''' Continuous communication must occur: we need interns able to initiate the communication from their side too when needed, and with a backup mentor, both can also ensure communications from our side work well too.

== Relations with education organisations ==

In Belgium, there are two kind of internships:
* through IFAPME — really bureaucratic, but they seem to want to adapt to organisations needs
* from superior schools and universities — either they don't care, either they clearly consider they can impose the rules

From France, we had problems with cases of on-site requirements during COVID-19 lockdowns.

Requirements from the school need to be taken in consideration:
* what's the obligation of the mentor?
* jury participation? lot of documents to fill?
* is hybrid work acceptable?

Experience shows we need in the future to refuse interns from schools with on-site requirements.

Internship guide/Best practices for mentors

2026-02-21T15:31:22Z

Dereckson: /* Rules we'd like to follow in the future */

== Context and experience ==

Nasqueron is a small-size open-source project and free culture community. When we offer an internship, the outcome is really different based on the motivation and the level of the intern.

Our experience is based on 7 internships offered and it's only the second year we offer such a program, so the experience is based on a small dataset.

The ideal intern is:
* self-directed
* motivated
* able to engage with the mentor

Remote / non-remote balance doesn't seem to matter — we had a lukewarm experience with an intern on-site and a stellar experience with a remote intern with big timezone difference. Our workflows allow remote connection.

Communication tools matter: we had good experiences with IRC and WhatsApp communication, mixed results on DevCentral integrated chat; we would like to experience what's going on with solutions like Mattermost/Zulip/Stoat/Slack/Discord.

The mentor seems to matter too:
* Dorian and Dereckson looks hard to win — you need to be a good to very good contributor to gain their approval, either technically or with eagerness to learn.
* Eli is clearly more open to help a newcomer to find their first steps and takes care not to overwhelm them.

== Rules we'd like to follow in the future ==
* '''Backup.''' We really need to have a backup mentor for each internship.
* '''Remote or hybrid.''' A minimal number of days on-site isn't acceptable.
* '''Experience.''' Projects engagement show we can provide a really more meaningful internship for experienced students.
* '''Favour ops/security/network track.''' Internships in non-dev is rather hard to find, and Nasqueron tasks seem really infrastructure-oriented, so we can provide real projects, experience, knowledge and culture. That works and that works well (80% success), so that's we clearly bring something on the table here and an opportunity for interns to grow. For developers, it seems more complicated: our practices and infrastructure are clearly tailored for developers at ease with complicated tooling and workflows.
* '''Initial engagement.''' Ideally, tooling training (arc/git workflow) should be offered beforehand. We should offer a small task to complete in that goal.
* '''Communication.''' Continuous communication must occur: we need interns able to initiate the communication from their side too when needed, and with a backup mentor, both can also ensure communications from our side work well too.

== Relations with education organisations ==

In Belgium, there are two kind of internships:
* through IFAPME — really bureaucratic, but they seem to want to adapt to organisations needs
* from superior schools and universities — either they don't care, either they clearly consider they can impose the rules

From France, we had problems with cases of on-site requirements during COVID-19 lockdowns.

Requirements from the school need to be taken in consideration:
* what's the obligation of the mentor?
* jury participation? lot of documents to fill?
* is hybrid work acceptable?

Experience shows we need in the future to refuse interns from schools with on-site requirements.

Internship guide/Best practices for mentors

2026-02-21T15:30:40Z

Dereckson: /* Rules we'd like to follow in the future */

== Context and experience ==

Nasqueron is a small-size open-source project and free culture community. When we offer an internship, the outcome is really different based on the motivation and the level of the intern.

Our experience is based on 7 internships offered and it's only the second year we offer such a program, so the experience is based on a small dataset.

The ideal intern is:
* self-directed
* motivated
* able to engage with the mentor

Remote / non-remote balance doesn't seem to matter — we had a lukewarm experience with an intern on-site and a stellar experience with a remote intern with big timezone difference. Our workflows allow remote connection.

Communication tools matter: we had good experiences with IRC and WhatsApp communication, mixed results on DevCentral integrated chat; we would like to experience what's going on with solutions like Mattermost/Zulip/Stoat/Slack/Discord.

The mentor seems to matter too:
* Dorian and Dereckson looks hard to win — you need to be a good to very good contributor to gain their approval, either technically or with eagerness to learn.
* Eli is clearly more open to help a newcomer to find their first steps and takes care not to overwhelm them.

== Rules we'd like to follow in the future ==
* '''Backup.''' We really need to have a backup mentor for each internship.
* '''Remote or hybrid.''' A minimal number of days on-site isn't acceptable.
* '''Experience.''' Projects engagement show we can provide a really more meaningful internship for experienced students.
* '''Favour ops/security/network track.''' Internships in non-dev is rather hard to find, and Nasqueron tasks seem really infrastructure-oriented, so we can provide real projects, experience, knowledge and culture. That works and that works well (80% success). For developers, it seems more complicated: our practices and infrastructure are clearly tailored for developers at ease with complicated tooling and workflows.
* '''Initial engagement.''' Ideally, tooling training (arc/git workflow) should be offered beforehand. We should offer a small task to complete in that goal.
* '''Communication.''' Continuous communication must occur: we need interns able to initiate the communication from their side too when needed, and with a backup mentor, both can also ensure communications from our side work well too.

== Relations with education organisations ==

In Belgium, there are two kind of internships:
* through IFAPME — really bureaucratic, but they seem to want to adapt to organisations needs
* from superior schools and universities — either they don't care, either they clearly consider they can impose the rules

From France, we had problems with cases of on-site requirements during COVID-19 lockdowns.

Requirements from the school need to be taken in consideration:
* what's the obligation of the mentor?
* jury participation? lot of documents to fill?
* is hybrid work acceptable?

Experience shows we need in the future to refuse interns from schools with on-site requirements.

Internship guide/Best practices for mentors

2026-02-21T15:30:05Z

Dereckson: Created page with "== Context and experience == Nasqueron is a small-size open-source project and free culture community. When we offer an internship, the outcome is really different based on the motivation and the level of the intern. Our experience is based on 7 internships offered and it's only the second year we offer such a program, so the experience is based on a small dataset. The ideal intern is: * self-directed * motivated * able to engage with the mentor Remote / non-remote b..."

== Context and experience ==

Nasqueron is a small-size open-source project and free culture community. When we offer an internship, the outcome is really different based on the motivation and the level of the intern.

Our experience is based on 7 internships offered and it's only the second year we offer such a program, so the experience is based on a small dataset.

The ideal intern is:
* self-directed
* motivated
* able to engage with the mentor

Remote / non-remote balance doesn't seem to matter — we had a lukewarm experience with an intern on-site and a stellar experience with a remote intern with big timezone difference. Our workflows allow remote connection.

Communication tools matter: we had good experiences with IRC and WhatsApp communication, mixed results on DevCentral integrated chat; we would like to experience what's going on with solutions like Mattermost/Zulip/Stoat/Slack/Discord.

The mentor seems to matter too:
* Dorian and Dereckson looks hard to win — you need to be a good to very good contributor to gain their approval, either technically or with eagerness to learn.
* Eli is clearly more open to help a newcomer to find their first steps and takes care not to overwhelm them.

== Rules we'd like to follow in the future ==
* '''Backup.''' We really need to have a backup mentor for each internship.
* '''Remote or hybrid.''' A minimal number of days on-site isn't acceptable.
* '''Experience.''' Projects engagement show we can provide a really more meaningful internship for experienced students.
* '''Favour ops/security/network track.''' Internships in non-dev is rather hard to find, and Nasqueron tasks seem really infrastructure-oriented, so we can provide real projects, experience, knowledge and culture. That works and that works well (80% success). For developers, it seems more complicated: our practices and infrastructure are clearly tailored for developers at ease with complicated tooling and workflows.
* '''Initial engagement.''' Ideally, tooling training (arc/git workflow) should be offered beforehand. We should offer a small task to complete in that goal.
* '''Communication.''' Continuous communication must occur: we need interns able to initiate the communication from their side too when needed.

== Relations with education organisations ==

In Belgium, there are two kind of internships:
* through IFAPME — really bureaucratic, but they seem to want to adapt to organisations needs
* from superior schools and universities — either they don't care, either they clearly consider they can impose the rules

From France, we had problems with cases of on-site requirements during COVID-19 lockdowns.

Requirements from the school need to be taken in consideration:
* what's the obligation of the mentor?
* jury participation? lot of documents to fill?
* is hybrid work acceptable?

Experience shows we need in the future to refuse interns from schools with on-site requirements.

Internship guide

2026-02-21T14:43:07Z

Dereckson: /* Resources for mentors */

== Resources for interns ==
* [[/Ergonomics]]
* [[/Onboarding]]
* [[How to communicate]]
* [[How to contribute code]]
* [https://devcentral.nasqueron.org/home/menu/view/174/ Contribute to projects] on DevCentral
* [[wolfplex:Mémento des stagiaires]] (French only)

== Resources for mentors ==
* [[/Best practices for mentors]]
* [[/Colleges, universities and schools]]

[[Category:Internship guide|*]]
[[Category:Nasqueron documentation]]

Docker-002

2026-02-20T18:51:47Z

Dereckson: /* Properties */ +IPv6

Docker Engine for production services. Supersedes [[Equatower]] and [[docker-001]].

== Properties ==
* Hypervisor: [[hyper-001]]
* Network
** IP - drake: 172.27.27.5
** IP - public: 51.255.124.9 - 2001:470:1f13:365::50f7:ba11/64

== Useful links ==
* [[Equatower]] contains still relevant notes
* [https://devcentral.nasqueron.org/source/operations/browse/main/pillar/paas/docker/docker-002/ Docker and containers configuration]
* [https://netbox.nasqueron.org/virtualization/virtual-machines/7/ NetBox] 🔒

[[Category:Servers]]

ServPulse/Development guide

2026-02-17T21:51:09Z

Dereckson: /* Git workflow */ Link to docs/workflow.md

== Getting started ==

git clone https://devcentral.nasqueron.org/source/servpulse.git
cd servpulse
cp .env.example .env
docker compose up

The application will be available at:
* Status page: http://localhost:8080
* API: http://localhost:3000/api

Tip: if you're maintainer of the project and need write access to the repository, you need to clone by SSH: <code>git clone ssh://vcs@devcentral.nasqueron.org:5022/source/servpulse.git</code>. If you've already cloned the repository, you can edit the URL in <code>.git/config</code>.

== Project structure ==

servpulse/
├── backend/ Express.js API server (MVC pattern)
│ ├── controllers/ Request handlers
│ ├── models/ Data access layer (raw pg queries)
│ ├── routes/ API route definitions
│ ├── middleware/ JWT authentication
│ ├── services/ Business logic (notifications, health checks)
│ ├── config/ App config (app.json) and database connection
│ └── __tests__/ Jest unit tests
├── frontend/ Vue.js 3 application
│ └── src/
│ ├── components/ Reusable UI components
│ ├── composables/ Vue 3 composables (useServices, useIncidents, etc.)
│ ├── views/ Page views (StatusPage, AdminDashboard, AdminLogin)
│ ├── plugins/ API client (Axios)
│ ├── utils/ Status helpers and formatters
│ └── router/ Vue Router config with auth guards
├── database/ SQL schema (init.sql)
└── docker-compose.yml

== Code conventions ==

* [[Code_conventions|Nasqueron conventions]]
* Single quotes for strings
* camelCase for variables and functions
* Vue 3 Composition API (<code><script setup></code>) for components
* Tailwind CSS utility classes for styling (no scoped styles)
* Raw pg queries in models (no ORM)

== How to add a new feature ==

=== Adding a backend resource ===

# Add table to <code>database/init.sql</code>
# Create <code>models/resourceModel.js</code> — raw pg queries
# Create <code>controllers/resourceController.js</code> — req/res handlers
# Create <code>routes/resourceRoutes.js</code> — Express router with auth where needed
# Register routes in <code>app.js</code>
# Add tests in <code>__tests__/controllers/resourceController.test.js</code>

=== Adding a frontend component ===

# Create <code>.vue</code> file in <code>src/components/</code> using <code><script setup></code>
# Use Tailwind classes and existing utilities from <code>@/utils/status</code>
# Import composables from <code>@/composables/</code> for data
# Add tests in <code>src/components/__tests__/</code>

== Axios integration ==

The API client is configured in <code>frontend/src/plugins/api.js</code>. It uses Axios with a base URL from <code>VITE_API_URL</code> and automatically attaches JWT tokens from localStorage via a request interceptor.

Composables (<code>useServices</code>, <code>useIncidents</code>, etc.) wrap the API calls and return reactive refs:

const { services, loading, error, fetchServices } = useServices()

== Testing ==

# Backend (Jest)
cd backend && npm test

# Frontend (Vitest)
cd frontend && npm run test:unit

== Git workflow ==

See {{Browse|servpulse|docs/workflow.md}} in the repository for the arc diff workflow.

[[Category:ServPulse|Development guide]]
[[Category:Developer guide]]

Template:Browse

2026-02-17T21:50:51Z

Dereckson: Created page with "<noinclude>== Example == <code><nowiki>{{Browse|servpulse|docs/workflow.md}}</nowiki></code> gives {{Browse|servpulse|docs/workflow.md}} </noinclude> [https://devcentral.nasqueron.org/source/{{{1}}}/browse/main/{{{2}}} {{{2}}}]"

<noinclude>== Example ==
<code><nowiki>{{Browse|servpulse|docs/workflow.md}}</nowiki></code> gives {{Browse|servpulse|docs/workflow.md}}

</noinclude>
[https://devcentral.nasqueron.org/source/{{{1}}}/browse/main/{{{2}}} {{{2}}}]

ServPulse/Development guide

2026-02-17T21:47:08Z

Dereckson: /* Getting started */ Update URL to https, note for maintainers write access = SSH

== Getting started ==

git clone https://devcentral.nasqueron.org/source/servpulse.git
cd servpulse
cp .env.example .env
docker compose up

The application will be available at:
* Status page: http://localhost:8080
* API: http://localhost:3000/api

Tip: if you're maintainer of the project and need write access to the repository, you need to clone by SSH: <code>git clone ssh://vcs@devcentral.nasqueron.org:5022/source/servpulse.git</code>. If you've already cloned the repository, you can edit the URL in <code>.git/config</code>.

== Project structure ==

servpulse/
├── backend/ Express.js API server (MVC pattern)
│ ├── controllers/ Request handlers
│ ├── models/ Data access layer (raw pg queries)
│ ├── routes/ API route definitions
│ ├── middleware/ JWT authentication
│ ├── services/ Business logic (notifications, health checks)
│ ├── config/ App config (app.json) and database connection
│ └── __tests__/ Jest unit tests
├── frontend/ Vue.js 3 application
│ └── src/
│ ├── components/ Reusable UI components
│ ├── composables/ Vue 3 composables (useServices, useIncidents, etc.)
│ ├── views/ Page views (StatusPage, AdminDashboard, AdminLogin)
│ ├── plugins/ API client (Axios)
│ ├── utils/ Status helpers and formatters
│ └── router/ Vue Router config with auth guards
├── database/ SQL schema (init.sql)
└── docker-compose.yml

== Code conventions ==

* [[Code_conventions|Nasqueron conventions]]
* Single quotes for strings
* camelCase for variables and functions
* Vue 3 Composition API (<code><script setup></code>) for components
* Tailwind CSS utility classes for styling (no scoped styles)
* Raw pg queries in models (no ORM)

== How to add a new feature ==

=== Adding a backend resource ===

# Add table to <code>database/init.sql</code>
# Create <code>models/resourceModel.js</code> — raw pg queries
# Create <code>controllers/resourceController.js</code> — req/res handlers
# Create <code>routes/resourceRoutes.js</code> — Express router with auth where needed
# Register routes in <code>app.js</code>
# Add tests in <code>__tests__/controllers/resourceController.test.js</code>

=== Adding a frontend component ===

# Create <code>.vue</code> file in <code>src/components/</code> using <code><script setup></code>
# Use Tailwind classes and existing utilities from <code>@/utils/status</code>
# Import composables from <code>@/composables/</code> for data
# Add tests in <code>src/components/__tests__/</code>

== Axios integration ==

The API client is configured in <code>frontend/src/plugins/api.js</code>. It uses Axios with a base URL from <code>VITE_API_URL</code> and automatically attaches JWT tokens from localStorage via a request interceptor.

Composables (<code>useServices</code>, <code>useIncidents</code>, etc.) wrap the API calls and return reactive refs:

const { services, loading, error, fetchServices } = useServices()

== Testing ==

# Backend (Jest)
cd backend && npm test

# Frontend (Vitest)
cd frontend && npm run test:unit

== Git workflow ==

See <code>docs/workflow.md</code> in the repository for the arc diff workflow.

[[Category:ServPulse|Development guide]]
[[Category:Developer guide]]

User:Inidal

2026-02-17T21:43:13Z

Dereckson: Dereckson moved page User:Inidal to User:Ieli: Automatically moved page while renaming the user "Inidal" to "Ieli"

#REDIRECT [[User:Ieli]]

User:Ieli

2026-02-17T21:43:13Z

Dereckson: Dereckson moved page User:Inidal to User:Ieli: Automatically moved page while renaming the user "Inidal" to "Ieli"

{{User
| Full name = Eli Iguer
| Presentation = I am a self-taught software developer based in Edmonton, Alberta, Canada 🇨🇦. My primary focus is on JavaScript and Python, but I am currently expanding my knowledge by learning Rust.

In addition to my technical skills, I have a background in human resource management. Outside of work, I enjoy writing and mixing music, which I share on platforms such as YouTube and Bandcamp.
| Projects = [[ServPulse]]<br />{{repo|notification-push}}
| DevCentral user feed = ieli
| DevCentral user board = user-ieli
| GitHub = ieliofficial
| Personal site = [https://inidal.dev/ Eli's Hub]
}}

Mail

2026-02-15T14:17:07Z

Dereckson:

Nasqueron maintains a mail infrastructure both for applications and for users.

For the operations grimoire, see [[Operations grimoire/Mail]].

== @nasqueron.org mail addresses ==
=== Use ===
To access your @nasqueron.org mailbox, you can use webmail or any client of your choice.

Webmail:
* https://mail.nasqueron.org/snappymail/

Server access:

;IMAP
* mail.nasqueron.org on port 143 with STARTTLS support
* mail.nasqueron.org on port 993 for TLS
;POP3
* mail.nasqueron.org on port 110 with STARTTLS support
* mail.nasqueron.org on port 995 for TLS
;SMTP
* mail.nasqueron.org on port 587 with STARTTLS
* The SMTP server requires authentication
* The port 25 SHOULD be restricted to server-to-server connections

Authentication:
* Your username is the FULL e-mail address, ie <code>user@nasqueron.org</code>, not only <code>user</code>
* Your password should work for IMAP, POP3 and SMTP servers

Guides:
* [[Connect to mail server with Thunderbird]]

To change password:
* If you know your password, it's self-service at https://admin.mail.nasqueron.org/auth/change-password
* If you lost your password, open a task on DevCentral, add #mail and #security projects

=== Create a new mailbox ===
You can open a ticket on https://devcentral.nasqueron.org/ and associate it to the Mail tag.

You can also ask on IRC Libera Chat #nasqueron-ops.

== Host a domain ==
Any open-source or free culture project can host a domain at Nasqueron for mail hosting.

When a domain uses reasonably low bandwidth and disk space (< 120 Gb), it can directly be hosted on our mail server, free of charge.

For domains needing more resources, we can deploy a new server. In such case, you'll need to enter a co-billing agreement.

'''Features:'''
* DKIM signature
* Help to setup DKIM, SPF and DMARC DNS records
* Web UI to create and manage mailboxes, aliases (ViMbAdmin) for your domains
* Webmail access
* POP3 / IMAP / SMTP access
* We can also setup mailing lists - we use Sympa at Nasqueron, possibility to setup Majordomo 2 or Mailman
* Participation to the governance discussions

'''To request'''

Open a task on [https://devcentral.nasqueron.org/ DevCentral] tagged with the Mail project where you present your open-source or free culture project and your needs. A member of Nasqueron Operations SIG will contact you and setup resources according your request.

== Domains ==

Mail core infrastructure:
* @nasqueron.org (general purpose, normal to high priority)
* @wolfplex.be and @wolfplex.org (for Wolfplex Hackerspace) and @ook.space (mainly a test domain)
* Yes, we can add custom domains there

Still to configure:
* @lists.nasqueron.org (mailing lists, low to normal priority)

Servers domains:
* @dwellers.nasqueron.org (not configured, low priority)
* @ysul.nasqueron.org (works)

Some subdomains are dedicated to applications and handled by 3rd party providers:
* @devcentral.nasqueron.org is managed by Mailgun for Phabricator ingoing and outgoing mail
* @discourse.nasqueron.org is managed by Mandrill for Discourse outgoing mail

No @*.nasqueron.org mail is handled by Google for applications.

== Get support ==

Angelina, Dorian and Dereckson can help you. Open a task on DevCentral to request support for any mail related task:

{{Call for action
|link=https://devcentral.nasqueron.org/maniphest/task/edit/form/1/?projects=mail&subscribers=dereckson,dorianwinty,aceppaluni
|text=Get mail support
}}

[[Category:Contributor guide]]
[[Category:Mail]]

Lexicon

2026-02-15T13:05:47Z

Dereckson: /* S */

This lexicon defines key terms, expressions, and internal concepts used across the Nasqueron open source project.

== B ==

; Bastion
: A hardened entry point to connect securely to the Nasqueron infrastructure, generally via SSH. Only the bastion is exposed to the Internet; internal hosts are accessed through it.
: 📖 [[Operations grimoire/Recommended SSH configuration]]

== C ==

; CARP
: Common Access Redundancy Protocol (CARP) is a protocol which allows multiple hosts to share the same IP address.
: 📖 [[Protocol CARP]]
: 📖 [https://docs.freebsd.org/en/books/handbook/advanced-networking/#carp FreeBSD Handbook]

== D ==

; DevCentral
: The name of the Phabricator/Phorge instance used at Nasqueron to coordinate tasks, track issues, and perform code reviews across projects.

== E ==

; Eglide
: A shell hosting project operated by Nasqueron members. Focused on providing traditional Linux shell environments for learning, scripting, and digital minimalism.
: 📖 [[Eglide]]

== F ==

; Forest
: A group of servers, with specific UNIX groups to create and users to provision. The concept of forest is only used for users/groups ACL, as services to provisions are by roles instead.

== H ==

; Hackerspace
: A collaborative community space where members share tools, skills, and ideas. Wolfplex Hackerspace serves as a physical counterpart to the online Nasqueron ecosystem.

; Infrastructure as Code (IaC)
: The practice of defining system configuration and provisioning entirely through cod using tools like Ansible, Terraform, SaltStack, ensuring reproducibility and transparency.

== K ==

; Keycloak
: The preferred open source solution for implementing Single Sign-On (SSO) and Identity Management (IDM) across Nasqueron services.

; Keruald
: Set of libraries to build PHP applications.
: [[Keruald]]

== M ==

; Manifest
: A YAML or JSON file describing configuration or metadata for a project, service, or deployment. Manifests are versioned in Git.

; Manyrepo
: A hybrid approach between monorepo and polyrepo, where related components are grouped together in a few larger repositories. Used in a few Nasqueron projects to balance modularity with ease of maintenance.
: A repository which looks like its own separate repository, but exported from a monorepo. Needed for some packages tooling like Composer. That's the strategy used to publish Keruald libraries.

; Monorepo
: A single repository containing multiple projects or components, allowing shared tooling, consistent dependency management, and atomic changes across modules.

== N ==

; Node
: A specific server in our Operations repository context. A node belongs to a forest. The server can be a physical server, a VM or a network appliance.

== O ==

; OmniTools
: A PHP library developed by Nasqueron, providing reusable utilities and abstractions across projects

; Omni-OS
: The infrastructure strategy combining FreeBSD, Rocky Linux / CentOS Stream, and Debian to leverage the strengths of multiple operating systems.

== P ==
; Polyrepo
: A source code organization strategy where each project or service has its own separate repository. Common when projects evolve independently or have different lifecycles.

== S ==

; ServPulse
: Project to create a status page.
: 📖 [[ServPulse]]

; SSO
: Single Sign-On. A centralized authentication mechanism allowing contributors to log in once to access multiple Nasqueron services seamlessly.

; Salt
: Refers to SaltStack, the configuration management tool used for provisioning and maintaining Nasqueron infrastructure nodes.

== T ==

; Tigraki
: Former server name, originating from the Aion universe. Represents curiosity and technical creativity.

== W ==

; Waystone
: A namespace for Obsidan Workspaces ecosystem, to use on Packagist/Composer, inspired by magical or navigational stones guiding travelers.

; WindRiver
: Dedicated development server
: 📖 [[WindRiver]], [[Devserver reference]]

; Wolfplex
: The physical hackerspace and community in Belgium linked to Nasqueron. Hosts events, experimentation, and outreach.

----

''This lexicon evolves with the project. Contributors are encouraged to expand and refine it as new terms appear or gain significance at Nasqueron.''

[[Category:Reference]]

Lexicon

2026-02-15T13:05:06Z

Dereckson: +CARP

This lexicon defines key terms, expressions, and internal concepts used across the Nasqueron open source project.

== B ==

; Bastion
: A hardened entry point to connect securely to the Nasqueron infrastructure, generally via SSH. Only the bastion is exposed to the Internet; internal hosts are accessed through it.
: 📖 [[Operations grimoire/Recommended SSH configuration]]

== C ==

; CARP
: Common Access Redundancy Protocol (CARP) is a protocol which allows multiple hosts to share the same IP address.
: 📖 [[Protocol CARP]]
: 📖 [https://docs.freebsd.org/en/books/handbook/advanced-networking/#carp FreeBSD Handbook]

== D ==

; DevCentral
: The name of the Phabricator/Phorge instance used at Nasqueron to coordinate tasks, track issues, and perform code reviews across projects.

== E ==

; Eglide
: A shell hosting project operated by Nasqueron members. Focused on providing traditional Linux shell environments for learning, scripting, and digital minimalism.
: 📖 [[Eglide]]

== F ==

; Forest
: A group of servers, with specific UNIX groups to create and users to provision. The concept of forest is only used for users/groups ACL, as services to provisions are by roles instead.

== H ==

; Hackerspace
: A collaborative community space where members share tools, skills, and ideas. Wolfplex Hackerspace serves as a physical counterpart to the online Nasqueron ecosystem.

; Infrastructure as Code (IaC)
: The practice of defining system configuration and provisioning entirely through cod using tools like Ansible, Terraform, SaltStack, ensuring reproducibility and transparency.

== K ==

; Keycloak
: The preferred open source solution for implementing Single Sign-On (SSO) and Identity Management (IDM) across Nasqueron services.

; Keruald
: Set of libraries to build PHP applications.
: [[Keruald]]

== M ==

; Manifest
: A YAML or JSON file describing configuration or metadata for a project, service, or deployment. Manifests are versioned in Git.

; Manyrepo
: A hybrid approach between monorepo and polyrepo, where related components are grouped together in a few larger repositories. Used in a few Nasqueron projects to balance modularity with ease of maintenance.
: A repository which looks like its own separate repository, but exported from a monorepo. Needed for some packages tooling like Composer. That's the strategy used to publish Keruald libraries.

; Monorepo
: A single repository containing multiple projects or components, allowing shared tooling, consistent dependency management, and atomic changes across modules.

== N ==

; Node
: A specific server in our Operations repository context. A node belongs to a forest. The server can be a physical server, a VM or a network appliance.

== O ==

; OmniTools
: A PHP library developed by Nasqueron, providing reusable utilities and abstractions across projects

; Omni-OS
: The infrastructure strategy combining FreeBSD, Rocky Linux / CentOS Stream, and Debian to leverage the strengths of multiple operating systems.

== P ==
; Polyrepo
: A source code organization strategy where each project or service has its own separate repository. Common when projects evolve independently or have different lifecycles.

== S ==

; SSO
: Single Sign-On. A centralized authentication mechanism allowing contributors to log in once to access multiple Nasqueron services seamlessly.

; Salt
: Refers to SaltStack, the configuration management tool used for provisioning and maintaining Nasqueron infrastructure nodes.

== T ==

; Tigraki
: Former server name, originating from the Aion universe. Represents curiosity and technical creativity.

== W ==

; Waystone
: A namespace for Obsidan Workspaces ecosystem, to use on Packagist/Composer, inspired by magical or navigational stones guiding travelers.

; WindRiver
: Dedicated development server
: 📖 [[WindRiver]], [[Devserver reference]]

; Wolfplex
: The physical hackerspace and community in Belgium linked to Nasqueron. Hosts events, experimentation, and outreach.

----

''This lexicon evolves with the project. Contributors are encouraged to expand and refine it as new terms appear or gain significance at Nasqueron.''

[[Category:Reference]]

Lexicon

2026-02-15T13:02:33Z

Dereckson: /* F */

This lexicon defines key terms, expressions, and internal concepts used across the Nasqueron open source project.

== B ==

; Bastion
: A hardened entry point to connect securely to the Nasqueron infrastructure, generally via SSH. Only the bastion is exposed to the Internet; internal hosts are accessed through it.
: 📖 [[Operations grimoire/Recommended SSH configuration]]

== D ==

; DevCentral
: The name of the Phabricator/Phorge instance used at Nasqueron to coordinate tasks, track issues, and perform code reviews across projects.

== E ==

; Eglide
: A shell hosting project operated by Nasqueron members. Focused on providing traditional Linux shell environments for learning, scripting, and digital minimalism.
: 📖 [[Eglide]]

== F ==

; Forest
: A group of servers, with specific UNIX groups to create and users to provision. The concept of forest is only used for users/groups ACL, as services to provisions are by roles instead.

== H ==

; Hackerspace
: A collaborative community space where members share tools, skills, and ideas. Wolfplex Hackerspace serves as a physical counterpart to the online Nasqueron ecosystem.

; Infrastructure as Code (IaC)
: The practice of defining system configuration and provisioning entirely through cod using tools like Ansible, Terraform, SaltStack, ensuring reproducibility and transparency.

== K ==

; Keycloak
: The preferred open source solution for implementing Single Sign-On (SSO) and Identity Management (IDM) across Nasqueron services.

; Keruald
: Set of libraries to build PHP applications.
: [[Keruald]]

== M ==

; Manifest
: A YAML or JSON file describing configuration or metadata for a project, service, or deployment. Manifests are versioned in Git.

; Manyrepo
: A hybrid approach between monorepo and polyrepo, where related components are grouped together in a few larger repositories. Used in a few Nasqueron projects to balance modularity with ease of maintenance.
: A repository which looks like its own separate repository, but exported from a monorepo. Needed for some packages tooling like Composer. That's the strategy used to publish Keruald libraries.

; Monorepo
: A single repository containing multiple projects or components, allowing shared tooling, consistent dependency management, and atomic changes across modules.

== N ==

; Node
: A specific server in our Operations repository context. A node belongs to a forest. The server can be a physical server, a VM or a network appliance.

== O ==

; OmniTools
: A PHP library developed by Nasqueron, providing reusable utilities and abstractions across projects

; Omni-OS
: The infrastructure strategy combining FreeBSD, Rocky Linux / CentOS Stream, and Debian to leverage the strengths of multiple operating systems.

== P ==
; Polyrepo
: A source code organization strategy where each project or service has its own separate repository. Common when projects evolve independently or have different lifecycles.

== S ==

; SSO
: Single Sign-On. A centralized authentication mechanism allowing contributors to log in once to access multiple Nasqueron services seamlessly.

; Salt
: Refers to SaltStack, the configuration management tool used for provisioning and maintaining Nasqueron infrastructure nodes.

== T ==

; Tigraki
: Former server name, originating from the Aion universe. Represents curiosity and technical creativity.

== W ==

; Waystone
: A namespace for Obsidan Workspaces ecosystem, to use on Packagist/Composer, inspired by magical or navigational stones guiding travelers.

; WindRiver
: Dedicated development server
: 📖 [[WindRiver]], [[Devserver reference]]

; Wolfplex
: The physical hackerspace and community in Belgium linked to Nasqueron. Hosts events, experimentation, and outreach.

----

''This lexicon evolves with the project. Contributors are encouraged to expand and refine it as new terms appear or gain significance at Nasqueron.''

[[Category:Reference]]

Lexicon

2026-02-15T13:02:01Z

Dereckson: /* M */

This lexicon defines key terms, expressions, and internal concepts used across the Nasqueron open source project.

== B ==

; Bastion
: A hardened entry point to connect securely to the Nasqueron infrastructure, generally via SSH. Only the bastion is exposed to the Internet; internal hosts are accessed through it.
: 📖 [[Operations grimoire/Recommended SSH configuration]]

== D ==

; DevCentral
: The name of the Phabricator/Phorge instance used at Nasqueron to coordinate tasks, track issues, and perform code reviews across projects.

== E ==

; Eglide
: A shell hosting project operated by Nasqueron members. Focused on providing traditional Linux shell environments for learning, scripting, and digital minimalism.
: 📖 [[Eglide]]

== F ==

; Forest
: A group of servers, with specific UNIX groups to create and users to provision.
: It's for ACL users/groups only, as services to provisions are by roles instead.

== H ==

; Hackerspace
: A collaborative community space where members share tools, skills, and ideas. Wolfplex Hackerspace serves as a physical counterpart to the online Nasqueron ecosystem.

; Infrastructure as Code (IaC)
: The practice of defining system configuration and provisioning entirely through cod using tools like Ansible, Terraform, SaltStack, ensuring reproducibility and transparency.

== K ==

; Keycloak
: The preferred open source solution for implementing Single Sign-On (SSO) and Identity Management (IDM) across Nasqueron services.

; Keruald
: Set of libraries to build PHP applications.
: [[Keruald]]

== M ==

; Manifest
: A YAML or JSON file describing configuration or metadata for a project, service, or deployment. Manifests are versioned in Git.

; Manyrepo
: A hybrid approach between monorepo and polyrepo, where related components are grouped together in a few larger repositories. Used in a few Nasqueron projects to balance modularity with ease of maintenance.
: A repository which looks like its own separate repository, but exported from a monorepo. Needed for some packages tooling like Composer. That's the strategy used to publish Keruald libraries.

; Monorepo
: A single repository containing multiple projects or components, allowing shared tooling, consistent dependency management, and atomic changes across modules.

== N ==

; Node
: A specific server in our Operations repository context. A node belongs to a forest. The server can be a physical server, a VM or a network appliance.

== O ==

; OmniTools
: A PHP library developed by Nasqueron, providing reusable utilities and abstractions across projects

; Omni-OS
: The infrastructure strategy combining FreeBSD, Rocky Linux / CentOS Stream, and Debian to leverage the strengths of multiple operating systems.

== P ==
; Polyrepo
: A source code organization strategy where each project or service has its own separate repository. Common when projects evolve independently or have different lifecycles.

== S ==

; SSO
: Single Sign-On. A centralized authentication mechanism allowing contributors to log in once to access multiple Nasqueron services seamlessly.

; Salt
: Refers to SaltStack, the configuration management tool used for provisioning and maintaining Nasqueron infrastructure nodes.

== T ==

; Tigraki
: Former server name, originating from the Aion universe. Represents curiosity and technical creativity.

== W ==

; Waystone
: A namespace for Obsidan Workspaces ecosystem, to use on Packagist/Composer, inspired by magical or navigational stones guiding travelers.

; WindRiver
: Dedicated development server
: 📖 [[WindRiver]], [[Devserver reference]]

; Wolfplex
: The physical hackerspace and community in Belgium linked to Nasqueron. Hosts events, experimentation, and outreach.

----

''This lexicon evolves with the project. Contributors are encouraged to expand and refine it as new terms appear or gain significance at Nasqueron.''

[[Category:Reference]]

Lexicon

2026-02-15T13:00:51Z

Dereckson: /* E */

This lexicon defines key terms, expressions, and internal concepts used across the Nasqueron open source project.

== B ==

; Bastion
: A hardened entry point to connect securely to the Nasqueron infrastructure, generally via SSH. Only the bastion is exposed to the Internet; internal hosts are accessed through it.
: 📖 [[Operations grimoire/Recommended SSH configuration]]

== D ==

; DevCentral
: The name of the Phabricator/Phorge instance used at Nasqueron to coordinate tasks, track issues, and perform code reviews across projects.

== E ==

; Eglide
: A shell hosting project operated by Nasqueron members. Focused on providing traditional Linux shell environments for learning, scripting, and digital minimalism.
: 📖 [[Eglide]]

== F ==

; Forest
: A group of servers, with specific UNIX groups to create and users to provision.
: It's for ACL users/groups only, as services to provisions are by roles instead.

== H ==

; Hackerspace
: A collaborative community space where members share tools, skills, and ideas. Wolfplex Hackerspace serves as a physical counterpart to the online Nasqueron ecosystem.

; Infrastructure as Code (IaC)
: The practice of defining system configuration and provisioning entirely through cod using tools like Ansible, Terraform, SaltStack, ensuring reproducibility and transparency.

== K ==

; Keycloak
: The preferred open source solution for implementing Single Sign-On (SSO) and Identity Management (IDM) across Nasqueron services.

; Keruald
: Set of libraries to build PHP applications.
: [[Keruald]]

== M ==

; Manifest
: A YAML or JSON file describing configuration or metadata for a project, service, or deployment. Manifests are versioned in Git.

; Manyrepo
: A hybrid approach between monorepo and polyrepo, where related components are grouped together in a few larger repositories. Used in a few Nasqueron projects to balance modularity with ease of maintenance.
: A repository which looks like its own separate repository, but exported from a monorepo. Needed for some packages tooling like Composer. That's the strategy used to publish Keruald libraries.

; Monorepo
: A single repository containing multiple projects or components, allowing shared tooling, consistent dependency management, and atomic changes across modules.

== O ==

; OmniTools
: A PHP library developed by Nasqueron, providing reusable utilities and abstractions across projects

; Omni-OS
: The infrastructure strategy combining FreeBSD, Rocky Linux / CentOS Stream, and Debian to leverage the strengths of multiple operating systems.

== P ==
; Polyrepo
: A source code organization strategy where each project or service has its own separate repository. Common when projects evolve independently or have different lifecycles.

== S ==

; SSO
: Single Sign-On. A centralized authentication mechanism allowing contributors to log in once to access multiple Nasqueron services seamlessly.

; Salt
: Refers to SaltStack, the configuration management tool used for provisioning and maintaining Nasqueron infrastructure nodes.

== T ==

; Tigraki
: Former server name, originating from the Aion universe. Represents curiosity and technical creativity.

== W ==

; Waystone
: A namespace for Obsidan Workspaces ecosystem, to use on Packagist/Composer, inspired by magical or navigational stones guiding travelers.

; WindRiver
: Dedicated development server
: 📖 [[WindRiver]], [[Devserver reference]]

; Wolfplex
: The physical hackerspace and community in Belgium linked to Nasqueron. Hosts events, experimentation, and outreach.

----

''This lexicon evolves with the project. Contributors are encouraged to expand and refine it as new terms appear or gain significance at Nasqueron.''

[[Category:Reference]]

Main Page

2026-02-14T18:45:38Z

Dereckson: /* Projects */

__NOTOC__
{{DISPLAYTITLE:<span style="color:white;width:0;font-size:0;">{{FULLPAGENAME}}</span>}}
<div style="margin-bottom: 2em;">
<div style="font-size: 3.75em; margin-bottom: 0.25em;" class="color-magnetic-three">Agora</div>
<div style="font-size: 3em;" class="color-magnetic-two">The Nasqueron wiki & collaboration space.</div>
<div class="block-col block-col-half">
== Welcome to Nasqueron ==

🏴 Nasqueron is a budding community of creative people, writers, developers and thinkers.

🌱👨🏽‍🤝‍👨🏼🧑🏾‍🤝‍🧑🏻🙋🏾‍♂️👩🏾 You'll find here like-minded people to connect to, hang out, and build projects.

📃 We focus on free culture, ethics and to be a positive change. Our software is open source our datasources and content are licensed under CC-BY-SA or CC-BY license. We share values like respect, justice and equity.

❤️ We like experiments, originality and to discover new things.

👽 We are Nasqueron.
</div>
<div class="block-col block-col-half">
== Agora ==
'''Agora''' is the Nasqueron wiki.

Like an Agora, it's intended to be a public open space used for assemblies, with a focus on collaboration.

📙📚✏️ As this is a wiki, feel free to edit it.<br>
You can [https://forms.nasqueron.org/nasqueron-requests/agora-account/new request an account here] or [irc://libera.chat/wolfplex ask on IRC].

You'll mostly find here:

* development and contribution information
* infrastructure / servers / operations documentation
* project ideas
* various notes
* the content you deem relevant

You can read this main page to explore content, [[Special:Search|do a search]] or [[:Category:Nasqueron root category|browse categories]].

</div>
<div class="clear"></div>
</div>

<div style="margin-bottom: 2em;">
<div style="font-size: 3.75em; margin-bottom: 0.25em;" class="color-magnetic-three">Contribute</div>
<div class="block-col block-col-half">

== Free culture & open source ==
;Guides
* [[How to contribute code]]
* [[Code conventions]]
* [[Dev policies]]
* [[Devserver reference]]
* [[AI content]]

;DevCentral
* [https://devcentral.nasqueron.org/tag/good-first-issue/ Good first issues]: you can start here if you would like a nice landing to our projects
* [https://devcentral.nasqueron.org/home/menu/view/174/ Contribute to projects]
* [https://devcentral.nasqueron.org/w/new-repo/ Create a new repository]

;Programs & resources
* [[Monday office hours]]
* [[Dev zone/Skills sharing]]
* [https://join.nasqueron.org Internship & Mentoring programs]
* [[Internship guide]]
* [[Nasqueron Labs]], workshops to explore new ideas

;Recipes
* [[Static sites]]
* [[Dev zone/Vault|Vault]]

;Dev notes for specific projects
* [[Limiting Factor]]
* [[Dev zone/Reports|Nasqueron Reports]]

== Services ==
* [[Planet]]
* [[Tools.nasqueron.org]]
* [[Social media accounts]]
* [[MediaWiki SaaS]]
* [[XMPP|Openfire instance]] (XMPP)
* [[Devserver reference|Development servers]]
</div>

<div class="block-col block-col-half">

== Infrastructure ==
* [[Operations grimoire]]
* [[Servers]] map

[[File:Nasqueron Operations Grimoire.jpg|thumb|right|The [[Operations grimoire‎|Nasqueron operations grimoire]] or '''NOG''', the reference to deal with anything on the servers]]

</div>
<div style="clear: both;"></div>
</div>

== Nasqueron? ==
* [[Poem]]
* To connect with the community, [[Zed]]
* To declare yourself a Nasqueron inhabitant, [[We are Nasqueron]]

== Projects ==
* [[Notifications center]]
* [[Nasqueron Datasources]]
* [[API]]
* [[ServPulse]]

; Current network work
* [[GRE tunnel]]
* [[Protocol CARP]]

; References
* [[Registries]] - OID, tags, XML schemas

; Consolidated resources
* [https://devcentral.nasqueron.org/project/ All projects on DevCentral]
* [[Projects index]]

; Draft projects ideas
* [[Tasacora]]
* [[Fastes consulaires]]
* [[Utopia Book Reader]]

== Pads ==
* [[Dereckson pad]]
* [[Design]]

== Events ==
* [[Hackathon geodata]]

== We participe to ==
* [[TrustSpace]]

ServPulse

2026-02-12T20:48:29Z

Dereckson: /* Team */

'''ServPulse''' is an open-source status-page platform for publishing the status of services, components, and infrastructure. Its goal is to make it easy to communicate incidents, maintenance, and uptime metrics in a transparent way.

ServPulse is designed to be self-hostable, simple to deploy, and extensible. It provides a foundation for teams and communities to manage status pages, integrate with monitoring tools, and notify users automatically.

The project is community-driven: contributions to the code, documentation, themes, integrations, or translations are all welcome. ServPulse aims to remain open, reliable, and adaptable to different environments, while keeping the setup and use straightforward.

== Technology stack ==
* Back-end
** Express.js service
** API documented according OpenAPI specification
** PostgreSQL database

* Front-end
** Vue.js
** Unit tests in [https://vitest.dev/ Vitest]
** API queried through [https://axios-http.com/docs/intro Axios]

== Team ==
* [https://devcentral.nasqueron.org/p/ieli/ Eli] (lead developer)
* Amine (developer)
* [[User:Dereckson|Dereckson]] (technical advisory)

Thanks for help to map stories:

* {{u|DorianWinty}}
* Fauve

== Discussion spaces ==
* Report issues: [https://devcentral.nasqueron.org/tag/servpulse/ DevCentral]
* Team discussions: [https://discord.gg/DZQK8Dd8Xd Discord]

== Activities ==
; Analysis
* [[/Note of Intent]]
* [[/Other existing solutions]]
* [[/Development guide]]
* [[/Project identity]]: why ServPulse name
* [[/Domain]]: names used in the project
* [[/User stories]]

== Useful links ==
* [https://devcentral.nasqueron.org/project/view/149/ DevCentral project board]
* [https://devcentral.nasqueron.org/source/servpulse/ Repository]

[[Category:ServPulse]]