423 lines
15 KiB
Markdown
423 lines
15 KiB
Markdown
# SMArT
|
||
|
||
SMArT is the web-based configuration interface for **MARS_NWE**, a Novell NetWare 3.x emulator for Linux and FreeBSD.
|
||
|
||
In the current setup, this repository is integrated into the main `mars_nwe` project as a **Git submodule**. It is built, installed, and released as part of the normal **MARS_NWE** release process rather than as a separate end-user component.
|
||
|
||
## Screenshots
|
||
|
||
The main menu is the normal entry point after login. It shows the available
|
||
configuration sections on the left and opens the selected explanation or editor
|
||
view on the right.
|
||
|
||
|
||
|
||
Additional UI examples:
|
||
|
||
<table>
|
||
<tr>
|
||
<td width="50%"><a href="doc/screenshots/login.png"><img src="doc/screenshots/thumbs/login.png" alt="Login screen"></a><br><strong>Login</strong><br>PAM-based login with SMArT session cookies.</td>
|
||
<td width="50%"><a href="doc/screenshots/service-runtime.png"><img src="doc/screenshots/thumbs/service-runtime.png" alt="Runtime information"></a><br><strong>Runtime information</strong><br>Configured paths, service name and project link.</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%"><a href="doc/screenshots/volumes-import.png"><img src="doc/screenshots/thumbs/volumes-import.png" alt="Volume import"></a><br><strong>Volume import</strong><br>Detected host mountpoints can be imported as MARS_NWE volumes.</td>
|
||
<td width="50%"><a href="doc/screenshots/user-editor.png"><img src="doc/screenshots/thumbs/user-editor.png" alt="User editor"></a><br><strong>User editor</strong><br>Optional Unix user mapping and bindery group membership.</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%"><a href="doc/screenshots/print-queue-cups.png"><img src="doc/screenshots/thumbs/print-queue-cups.png" alt="Print queue CUPS integration"></a><br><strong>Print queues</strong><br>CUPS printer selection can prefill the Unix print command.</td>
|
||
<td width="50%"><a href="doc/screenshots/smart-settings.png"><img src="doc/screenshots/thumbs/smart-settings.png" alt="SMArT settings"></a><br><strong>SMArT settings</strong><br>Bindery server settings and server-name synchronization.</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%"><a href="doc/screenshots/general-settings.png"><img src="doc/screenshots/thumbs/general-settings.png" alt="General settings"></a><br><strong>General settings</strong><br>Core MARS_NWE options with synchronized bindery naming.</td>
|
||
<td width="50%"><a href="doc/screenshots/advanced-path-settings.png"><img src="doc/screenshots/thumbs/advanced-path-settings.png" alt="Advanced path settings"></a><br><strong>Advanced sections</strong><br>Only the matching advanced section is displayed for the selected menu item.</td>
|
||
</tr>
|
||
<tr>
|
||
<td width="50%"><a href="doc/screenshots/validation-error.png"><img src="doc/screenshots/thumbs/validation-error.png" alt="Validation error"></a><br><strong>Validation errors</strong><br>Invalid input is rejected with a focused error page and a back action.</td>
|
||
<td width="50%"><a href="doc/screenshots/service-control.png"><img src="doc/screenshots/thumbs/service-control.png" alt="Service control output"></a><br><strong>Service control</strong><br>Start, stop, restart and status output for the configured MARS_NWE service.</td>
|
||
</tr>
|
||
</table>
|
||
|
||
## Project status and integration
|
||
|
||
This repository is intended to be embedded into the main `mars_nwe` Git repository:
|
||
|
||
- Main project: `mars_nwe`
|
||
- Submodule role: provides the SMArT web UI and helper tools
|
||
- Release model: shipped as part of the integrated **MARS_NWE** release
|
||
|
||
The build and install rules install the web UI binary, Perl helpers, configuration template, static assets, systemd unit, and PAM file as part of the integrated installation target.
|
||
|
||
## Architecture overview
|
||
|
||
SMArT consists of three main pieces:
|
||
|
||
1. **`nwwebui`** – a dedicated HTTP/HTTPS frontend service
|
||
2. **Perl helper scripts** – request routing, configuration pages, bindery operations, validation, and service control
|
||
3. **Small native helpers** – PAM login checking and optional user enumeration helpers
|
||
|
||
The `nwwebui` service can expose the UI over:
|
||
|
||
- **HTTP on port 9080**
|
||
- **HTTPS on port 9443**
|
||
|
||
Both listeners can run in parallel. HTTPS is recommended for real deployments because the login form transmits credentials. Plain HTTP is still useful for local testing or trusted internal environments.
|
||
|
||
## Major features
|
||
|
||
### HTML login, sessions, and logout
|
||
|
||
SMArT provides a form-based login page, session cookies, and a logout action. Static assets such as the SMArT logo are served before authentication so the login page can render correctly.
|
||
|
||
Runtime session files are stored under the WebUI runtime directory, typically:
|
||
|
||
```text
|
||
/run/mars-nwe-webui
|
||
```
|
||
|
||
### PAM authentication with administrator group restriction
|
||
|
||
Authentication is performed through the PAM service `smart` using the `check_login` helper. In addition to a successful PAM login, the user must be a member of the configured Unix administrator group.
|
||
|
||
The administrator group is configured at build time through the main `mars_nwe` CMake project:
|
||
|
||
```bash
|
||
cmake -DMARS_NWE_SMART_ADMIN_GROUP=root ...
|
||
```
|
||
|
||
The default is `root` to preserve the traditional behavior on existing systems. On normal Unix systems the `root` user has primary group `root`, so root can still log in. For delegated administration, build with a dedicated group instead:
|
||
|
||
```bash
|
||
cmake -DMARS_NWE_SMART_ADMIN_GROUP=nwadmin ...
|
||
groupadd nwadmin
|
||
usermod -aG nwadmin mario
|
||
```
|
||
|
||
After installation the effective setting appears in `smart.conf` as:
|
||
|
||
```perl
|
||
$smart_admin_group = 'root';
|
||
```
|
||
|
||
or, for a delegated build:
|
||
|
||
```perl
|
||
$smart_admin_group = 'nwadmin';
|
||
```
|
||
|
||
### Service control page
|
||
|
||
The start page includes controls for the configured MARS_NWE service:
|
||
|
||
- start
|
||
- stop
|
||
- restart
|
||
- status
|
||
|
||
The service name is supplied by the build configuration and can be overridden in `smart.conf`:
|
||
|
||
```perl
|
||
$mars_nwe_service = 'mars-nwe-serv.service';
|
||
$smart_systemctl_path = '/usr/bin/systemctl';
|
||
```
|
||
|
||
### Runtime information page
|
||
|
||
The start page shows the important runtime paths generated by CMake, including:
|
||
|
||
- main MARS_NWE configuration file
|
||
- SMArT configuration file
|
||
- WebUI helper/script directory
|
||
- MARS_NWE service unit name
|
||
- `systemctl` executable
|
||
|
||
This helps diagnose packaging or installation path issues without searching through generated files.
|
||
|
||
### Configuration editors and advanced sections
|
||
|
||
The main menu contains the commonly used configuration areas and advanced sections. Advanced pages are shown only when the selected section is opened, which keeps the menu usable while still exposing low-level MARS_NWE options.
|
||
|
||
Current sections include, among others:
|
||
|
||
- setup first
|
||
- MARS_NWE service
|
||
- general settings
|
||
- directories
|
||
- precompiled/path settings
|
||
- security
|
||
- user configuration
|
||
- volumes
|
||
- devices
|
||
- logging
|
||
- stations/access control
|
||
- users
|
||
- groups
|
||
- print queues
|
||
|
||
### Import helpers
|
||
|
||
SMArT can prefill or discover host-side data for common configuration tasks:
|
||
|
||
- local mount points for volume creation
|
||
- Unix users for MARS_NWE user mapping
|
||
- CUPS printers for print queue command generation
|
||
- IPX interfaces for device configuration
|
||
|
||
These helpers are meant to reduce manual typing while still leaving the final configuration under administrator control.
|
||
|
||
### Validation and error pages
|
||
|
||
The apply path validates common input before writing configuration or changing bindery data. Invalid values are shown on a dedicated validation page instead of failing silently or returning an empty HTTP response.
|
||
|
||
Validation currently covers areas such as:
|
||
|
||
- volume names and Unix paths
|
||
- device/network parameters
|
||
- print queue names, print commands, and spool directories
|
||
- user names and group names
|
||
- invalid bindery characters
|
||
|
||
### Bindery command handling
|
||
|
||
Bindery operations are executed through checked helper functions instead of silent `system()` calls. The WebUI logs command start, command success, command failure, and relevant output.
|
||
|
||
Commands such as `nwbocreate`, `nwbprm`, and `nwborm` are handled through `run_bindery_cmd()`. Pipe-style `nwbpset` operations are handled through `run_bindery_pipe()` using a temporary input file and checked return code.
|
||
|
||
This improves diagnostics for user, group, and print queue operations. The browser receives a structured error page when a bindery command fails.
|
||
|
||
### Bindery success pages
|
||
|
||
After successful user, group, or print queue changes, SMArT can show a result page with the number of successful bindery commands. This makes bindery changes visible to the administrator and avoids silent redirects after complex operations.
|
||
|
||
### Optional Unix user mapping updates
|
||
|
||
Existing MARS_NWE users no longer have their `UNIX_USER` mapping removed unless the administrator explicitly requests a mapping change. This prevents accidental loss of Unix user assignments when only editing full name, password, or group membership.
|
||
|
||
## Logging
|
||
|
||
SMArT has two relevant log streams:
|
||
|
||
- the `nwwebui` service log
|
||
- the Perl frontend log, normally `smart.log`
|
||
|
||
Typical paths:
|
||
|
||
```text
|
||
/var/log/mars_nwe/nwwebui.log
|
||
/var/log/mars_nwe/smart.log
|
||
```
|
||
|
||
### Perl frontend log level
|
||
|
||
The Perl frontend log level is configured in `smart.conf`:
|
||
|
||
```perl
|
||
# SMArT Perl logging verbosity.
|
||
# Values: error, warning, info, debug, trace
|
||
# Default: info
|
||
$smart_debug_level = 'info';
|
||
```
|
||
|
||
Supported values, from quiet to verbose:
|
||
|
||
- `error` – only real errors that abort or fail an operation
|
||
- `warning` – errors and warnings about unusual but non-fatal situations
|
||
- `info` – normal operational messages, command start/finish, default
|
||
- `debug` – additional diagnostic information for troubleshooting
|
||
- `trace` – very verbose step-by-step traces, including bindery pipe payloads
|
||
|
||
Use `trace` only while debugging a concrete problem. It may include submitted bindery payload data and can produce a lot of log output. After debugging, switch back to `info`.
|
||
|
||
### `nwwebui` service log level
|
||
|
||
The `nwwebui` service has its own numeric log level:
|
||
|
||
```perl
|
||
$nw_log_level = 1;
|
||
```
|
||
|
||
Typical meanings:
|
||
|
||
- `0` = errors only
|
||
- `1` = informational messages
|
||
- `2` = debug output
|
||
|
||
## Installed components
|
||
|
||
### Binaries
|
||
|
||
- `nwwebui` – dedicated web service frontend
|
||
- `check_login` – PAM authentication and administrator-group helper
|
||
- optional host discovery helpers, depending on build options
|
||
|
||
### Perl helpers
|
||
|
||
- `smart`
|
||
- `apply.pl`
|
||
- `readconfig.pl`
|
||
- `settings.pl`
|
||
- `static.pl`
|
||
- `control`
|
||
|
||
### Configuration and assets
|
||
|
||
- `smart.conf`
|
||
- static HTML/image assets for the WebUI
|
||
- optional `mars-nwe-webui.service` systemd unit
|
||
- PAM file installed as `/etc/pam.d/smart`
|
||
|
||
## Typical runtime paths
|
||
|
||
The templates use CMake placeholders. In a typical Linux installation, the effective paths are similar to:
|
||
|
||
- Main MARS_NWE config directory: `/etc/mars_nwe`
|
||
- SMArT config file: `/etc/mars_nwe/smart.conf`
|
||
- Main MARS_NWE server config: `/etc/mars_nwe/nwserv.conf`
|
||
- Helper binaries and scripts: `/usr/libexec/mars_nwe`
|
||
- Static SMArT assets: `/usr/libexec/mars_nwe/static`
|
||
- Log directory: `/var/log/mars_nwe`
|
||
- Runtime/session directory: `/run/mars-nwe-webui`
|
||
- PID directory: `/run/mars_nwe`
|
||
- TLS certificate: `/etc/mars_nwe/server.crt`
|
||
- TLS private key: `/etc/mars_nwe/server.key`
|
||
- PAM file: `/etc/pam.d/smart`
|
||
|
||
Packaging may adjust these paths depending on the target distribution.
|
||
|
||
## `smart.conf` example
|
||
|
||
A documented example with standard installation paths:
|
||
|
||
```perl
|
||
# Main MARS_NWE configuration
|
||
$mars_config = '/etc/mars_nwe/nwserv.conf';
|
||
$nonroot_user = 'nobody';
|
||
$smart_compact_nwservconf = 0;
|
||
|
||
# SMArT internal file layout
|
||
$smart_conf_path = '/etc/mars_nwe/smart.conf';
|
||
$smart_nwclient_path = '/etc/mars_nwe/.nwclient';
|
||
$smart_static_dir = '/usr/libexec/mars_nwe/static';
|
||
$smart_log_path = '/var/log/mars_nwe/smart.log';
|
||
$smart_check_login = '/usr/libexec/mars_nwe/check_login';
|
||
$smart_admin_group = 'root';
|
||
|
||
# Perl frontend logging
|
||
$smart_debug_level = 'info';
|
||
|
||
# Service control
|
||
$mars_nwe_service = 'mars-nwe-serv.service';
|
||
$smart_systemctl_path = '/usr/bin/systemctl';
|
||
|
||
# CUPS helper integration
|
||
$smart_cups_enable = '1';
|
||
$smart_cups_lpstat_path = '/usr/bin/lpstat';
|
||
$smart_cups_print_command_template = '/usr/bin/lp -d %p -';
|
||
|
||
# nwwebui listener settings
|
||
$nw_bind_ip = '0.0.0.0';
|
||
$nw_log_level = 1;
|
||
$nw_daemonize = 0;
|
||
$nw_pid_file = '/run/mars_nwe/nwwebui.pid';
|
||
$nw_log_file = '/var/log/mars_nwe/nwwebui.log';
|
||
|
||
$nw_ssl_enable = 0;
|
||
$nw_http_port = 9080;
|
||
$nw_https_port = 9443;
|
||
|
||
$nw_cert_file = '/etc/mars_nwe/server.crt';
|
||
$nw_key_file = '/etc/mars_nwe/server.key';
|
||
```
|
||
|
||
## Recent SMArT WebUI features
|
||
|
||
The current WebUI includes several usability and safety improvements:
|
||
|
||
- HTML login, session cookies and logout handling
|
||
- static asset serving before login, so the login page can load the SMArT logo
|
||
- service-control pages for start, stop, restart and status actions
|
||
- runtime information on the start page, including generated paths and service name
|
||
- import helpers for CUPS printers, IPX interfaces, Unix users and local mountpoints
|
||
- input validation pages for volumes, devices, print queues, users and groups
|
||
- stricter bindery object-name validation
|
||
- optional Unix user mapping for bindery users
|
||
- delete confirmation pages
|
||
- bindery command and bindery pipe logging
|
||
- success and error pages for bindery operations
|
||
- a `UNIX_USER` guard so existing users are not remapped unless requested
|
||
- configurable Perl log verbosity through `$smart_debug_level`
|
||
|
||
## Build and installation notes
|
||
|
||
This repository is built as part of the main `mars_nwe` build. The build system:
|
||
|
||
- generates `smart.conf` from the template
|
||
- generates the main `smart` Perl launcher script
|
||
- builds `nwwebui`
|
||
- builds `check_login`
|
||
- installs the PAM file and static UI assets
|
||
- installs helper scripts and optional systemd units
|
||
|
||
Useful build-time settings include:
|
||
|
||
```bash
|
||
cmake -DMARS_NWE_SMART_ADMIN_GROUP=root ...
|
||
cmake -DMARS_NWE_SMART_ADMIN_GROUP=nwadmin ...
|
||
cmake -DMARS_NWE_SYSTEMD_SERVICE=mars-nwe-serv.service ...
|
||
```
|
||
|
||
The administrator group defaults to `root` for compatibility. Use a dedicated group such as `nwadmin` when non-root administrators should be allowed to access the WebUI.
|
||
|
||
## Starting the service
|
||
|
||
### Starting with systemd
|
||
|
||
A typical installed system uses the `mars-nwe-webui.service` unit:
|
||
|
||
```bash
|
||
systemctl enable --now mars-nwe-webui.service
|
||
systemctl start mars-nwe-webui.service
|
||
systemctl stop mars-nwe-webui.service
|
||
systemctl restart mars-nwe-webui.service
|
||
systemctl status mars-nwe-webui.service
|
||
```
|
||
|
||
The service starts `nwwebui` with the equivalent of:
|
||
|
||
```bash
|
||
/usr/sbin/nwwebui -c /etc/mars_nwe/smart.conf
|
||
```
|
||
|
||
### Starting from the command line
|
||
|
||
```text
|
||
Usage: nwwebui [-h] [-d] [-s] [-c <smart.conf>] [-p <pidfile>] [-l <logfile>]
|
||
|
||
Options:
|
||
-h, --help Show this help text and exit
|
||
-d, --daemon Run in daemon mode
|
||
-s, --stop Stop the running nwwebui instance
|
||
-c, --config <file> Use an alternate smart.conf path
|
||
-p, --pidfile <file> Override PID file path
|
||
-l, --logfile <file> Override log file path
|
||
```
|
||
|
||
Examples:
|
||
|
||
```bash
|
||
/usr/sbin/nwwebui -c /etc/mars_nwe/smart.conf
|
||
/usr/sbin/nwwebui -d -c /etc/mars_nwe/smart.conf
|
||
/usr/sbin/nwwebui -s -c /etc/mars_nwe/smart.conf
|
||
/usr/sbin/nwwebui -c /etc/mars_nwe/smart.conf -l /var/log/mars_nwe/custom-nwwebui.log
|
||
```
|
||
|
||
Typical access URLs:
|
||
|
||
- `http://<host>:9080/`
|
||
- `https://<host>:9443/`
|
||
|
||
For production use, HTTPS should be preferred.
|
||
|
||
## Summary
|
||
|
||
SMArT is now an integrated part of the `mars_nwe` release. It includes a dedicated `nwwebui` service, form-based sessions, PAM authentication with configurable administrator group restriction, service control, validation pages, import helpers, improved bindery command handling, and configurable logging.
|