You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
SMBstack is an open-source Samba stack installer for Debian-based systems. It deploys a shared folder with Recycle Bin, full audit logging via rsyslog, a web-based audit viewer, and a shared folder browser — all configured interactively through a single installer script.
SMBstack es un instalador de stack Samba de código abierto para sistemas basados en Debian. Despliega una carpeta compartida con Papelera de Reciclaje, auditoría completa vía rsyslog, un visor web de auditoría y un explorador web de la carpeta compartida — todo configurado de forma interactiva a través de un único script instalador.
There are two ways to reach each view: http://localhost:3092/?tab=audit or http://localhost:3092/audit for the audit viewer, and http://localhost:3092/?tab=shared or http://localhost:3092/shared for the shared folder browser. Both forms are valid.
Hay dos maneras de llegar a cada vista: http://localhost:3092/?tab=audit o http://localhost:3092/audit para el visor de auditoría, y http://localhost:3092/?tab=shared o http://localhost:3092/shared para el explorador de carpeta compartida. Ambas formas son válidas.
SMBaudit
The audit viewer (http://localhost:3092/?tab=audit) displays Samba activity logs in real time. It allows filtering by date range, IP and action, free-text search, pagination, and export to PDF.
El visor de auditoría (http://localhost:3092/?tab=audit) muestra los logs de actividad de Samba en tiempo real. Permite filtrar por rango de fechas, IP y acción, búsqueda de texto libre, paginación, y exportación a PDF.
Records are paginated (50/100/200/500 per page) with page navigation, so large audit logs stay responsive.
Los registros están paginados (50/100/200/500 por página) con navegación entre páginas, para que los logs de auditoría extensos se mantengan ágiles.
SMBshared
The shared folder browser (http://localhost:3092/) provides a unified interface with two tabs: Shared and Audit. The Shared tab allows navigating the shared folder structure, opening or downloading documents, and moving items to the recycle bin. Root-level folders are protected — items cannot be uploaded, created, or deleted from the root level.
El explorador de carpeta compartida (http://localhost:3092/) ofrece una interfaz unificada con dos pestañas: Shared y Audit. La pestaña Shared permite navegar la estructura de carpetas, abrir o descargar documentos y mover elementos a la papelera de reciclaje. Las carpetas de primer nivel están protegidas — no se pueden subir archivos, crear carpetas ni eliminar elementos desde la raíz.
Both views support a light/dark theme toggle from the top bar, synced across tabs.
Ambas vistas admiten un interruptor de tema claro/oscuro desde la barra superior, sincronizado entre pestañas.
Inside any subfolder, the toolbar allows uploading single or multiple files simultaneously, creating new folders, and reloading the view. All operations are recorded in the audit log with the client's IP address.
Dentro de cualquier subcarpeta, la barra de herramientas permite subir uno o varios archivos simultáneamente, crear nuevas carpetas y recargar la vista. Todas las operaciones quedan registradas en el log de auditoría con la IP del cliente.
Images and PDF files can be previewed inline via a modal (Preview button) without downloading them. Other file types keep the View button, which opens the file in a new tab.
Las imágenes y archivos PDF pueden previsualizarse en un modal (botón Preview) sin necesidad de descargarlos. El resto de tipos de archivo conserva el botón View, que abre el archivo en una nueva pestaña.
Files can also be uploaded by dragging and dropping them onto the upload panel, in addition to the file selector. A progress bar tracks the upload in real time.
Los archivos también pueden subirse arrastrándolos y soltándolos sobre el panel de subida, además del selector de archivos. Una barra de progreso muestra el avance de la subida en tiempo real.
SMBstack is installable as a Progressive Web App (PWA) on Chrome, Edge, and Safari (iOS/macOS), including offline access to the app shell. Firefox Desktop does not support PWA installation (removed since Firefox 85) — the app still works normally in the browser, just without the native install prompt.
SMBstack es instalable como Progressive Web App (PWA) en Chrome, Edge y Safari (iOS/macOS), incluyendo acceso sin conexión al shell de la app. Firefox Desktop no soporta instalación de PWA (eliminado desde Firefox 85) — la app sigue funcionando con normalidad en el navegador, solo sin el aviso nativo de instalación.
Scope
What SMBstack does:
Installs and configures Samba with a shared folder, Recycle Bin and group permissions
Configures full audit logging via rsyslog to /var/log/samba/log.audit
Deploys a web-based audit log viewer at http://localhost:3092/?tab=audit
Deploys a web-based shared folder browser at http://localhost:3092/?tab=shared
Configures logrotate for all Samba logs
Installs a service watchdog (smbload.sh) via cron every 5 minutes
Installs a shared folder size monitor (smbwatch.sh) — self-managed, independent of the installer
Saves installation config to /var/www/smbstack/smbstack.env for future updates
NetBIOS disabled by default (enable manually if needed, see NetBIOS section)
Lo que SMBstack hace:
Instala y configura Samba con carpeta compartida, Papelera de Reciclaje y permisos de grupo
Configura auditoría completa vía rsyslog en /var/log/samba/log.audit
Despliega un visor web de auditoría en http://localhost:3092/?tab=audit
Despliega un explorador web de la carpeta compartida en http://localhost:3092/?tab=shared
Configura logrotate para todos los logs de Samba
Instala un watchdog de servicios (smbload.sh) vía cron cada 5 minutos
Instala un monitor de espacio de la carpeta compartida (smbwatch.sh) — autogestionado, independiente del instalador
Guarda la configuración de instalación en /var/www/smbstack/smbstack.env para futuras actualizaciones
NetBIOS deshabilitado por defecto (actívalo manualmente si lo necesitas, ver sección NetBIOS)
Out of scope (not implemented):
Active Directory / domain controller
Multiple shared folders
Custom paths outside /home/$local_user/ (must be edited manually)
IPv6
LDAP
Fuera de alcance (no implementado):
Active Directory / controlador de dominio
Múltiples carpetas compartidas
Rutas personalizadas fuera de /home/$local_user/ (debe editarse manualmente)
IPv6
LDAP
Repository Structure
smbstack/
├── acl/ # Static access-control lists for Samba
│ └── commonveto.txt # Veto list for common unwanted file types (active by default in smb.conf)
├── conf/ # Samba and rsyslog configuration
│ ├── fullaudit.conf # rsyslog full audit rule
│ └── smb.conf # Samba main config (placeholders: your_user, compartida)
├── docs/ # Documentation licenses
│ └── LICENSE-CC-BY-NC-ND-4.0.md
├── img/ # Screenshots used throughout this README
│ ├── smbstack-botton.png
│ ├── smbstack-files.png
│ ├── smbstack-main.png
│ └── smbstack-views.png
├── tools/ # Background watchdog scripts
│ ├── smbload.sh # Service watchdog (smbd + winbind + smbwatch)
│ └── smbwatch.sh # Shared folder size monitor (self-managed)
├── web/ # Web front-end for the audit log viewer and shared-folder browser
│ ├── icon.svg # PWA / apple-touch icon
│ ├── index.php # Main page (Audit / Shared tabs)
│ ├── manifest.json # PWA manifest
│ ├── shared.php # Shared folder dynamic browser
│ ├── smbapi.php # Audit log reader API
│ ├── smbaudit-diagnostic.php # Audit log diagnostic tool
│ ├── smbaudit.html # Audit log viewer UI
│ ├── smbweb.conf # Apache vhost (:3092/?tab=audit and :3092/?tab=shared)
│ └── sw.js # PWA service worker (app-shell cache only)
├── LICENSE # GPL-3.0 (scripts, binaries, infrastructure)
└── smbinstall.sh # Installer: install, update, uninstall, status
Files and directories generated at runtime (not included in the repository):
Archivos y directorios generados en runtime (no incluidos en el repositorio):
/var/www/smbstack/
├── .size_cache/ # Folder size cache used by shared.php (www-data, created by the installer)
├── tools/ # Deployed copy of tools/*.sh
├── web/ # Deployed copy of web/ (served by Apache on :3092)
└── smbstack.env # Saved install config (user, paths, network, trusted proxies, watch limit, max log lines)
/etc/bak/smbstack/ # Archives written by --update (smbstackbak_<YYYYMMDD_HHMM>.zip, last 3 kept)
/etc/bak/crontab/root.bak # Copy of root's crontab, taken before any cron entry is added or removed
/var/log/smbwatch.log # smbwatch.sh runtime log (root:root, 640)
/var/log/smbload.log # smbload.sh runtime log
/home/$local_user/shared/ # Shared folder (independent of the installer)
├── .recycle/ # Recycle Bin (smbguest/, www-data/, smbwatch/)
└── DEMO/ # Demo folder
/etc/logrotate.d/samba # Generated by installer (heredoc)
/etc/logrotate.d/smbwatch # Generated by installer (heredoc), rotates /var/log/smbwatch.log
/var/log/samba/log.audit # Created by rsyslog
/var/log/samba/log.samba # Created by installer, written directly by smbd
/etc/samba/acl/commonveto.txt # Copied from acl/commonveto.txt by the installer
Before adding or removing any cron entry, smbinstall.sh and tools/smbwatch.sh copy root's crontab to /etc/bak/crontab/root.bak. It is a single copy, overwritten on every run, shared with every other project that touches the same crontab, and it is never restored automatically. --uninstall does not restore it either: it deletes only its own entries, matched by the full script path, and leaves every other cron job untouched. To roll back, restore the copy by hand with crontab /etc/bak/crontab/root.bak.
Antes de agregar o quitar cualquier entrada de cron, smbinstall.sh y tools/smbwatch.sh copian el crontab de root en /etc/bak/crontab/root.bak. Es una sola copia, sobrescrita en cada ejecución, compartida con cualquier otro proyecto que toque el mismo crontab, y nunca se restaura de forma automática. --uninstall tampoco la restaura: borra únicamente sus propias entradas, identificadas por la ruta completa del script, y deja intactas las demás tareas de cron. Para deshacer un cambio, restaura la copia a mano con crontab /etc/bak/crontab/root.bak.
HOW TO USE
Install
Download the repository and run the installer:
Descarga el repositorio y ejecuta el instalador:
git clone --depth=1 https://github.com/maravento/smbstack.git
cd smbstack
sudo bash smbinstall.sh
# or, to skip the menu and install directly | o, para saltar el menú e instalar directamente
sudo bash smbinstall.sh --install
The installer will prompt for:
Prompt
Description
Shared folder name
Name for the shared folder (created under /home/$local_user/)
Samba server network
IP/network in CIDR format (e.g. 192.168.0.0/24)
Network interface
Selected from available interfaces listed
Samba username
Samba account to create
Overwrite smb.conf
Only asked if /etc/samba/smb.conf already exists
$local_user is the local Linux user detected automatically by the installer: among users within the system's normal UID range (UID_MIN-UID_MAX from /etc/login.defs, excluding /false//nologin shells) who belong to the sudo group, the one with the lowest UID is selected. It becomes the owner of the shared folder and the base name for the Samba account.
$local_user es el usuario local de Linux detectado automáticamente por el instalador: entre los usuarios dentro del rango normal de UID (UID_MIN-UID_MAX de /etc/login.defs, excluyendo shells /false//nologin) que pertenezcan al grupo sudo, se selecciona el de menor UID. Se convierte en el propietario de la carpeta compartida y el nombre base de la cuenta Samba.
Update & Uninstall
To update or uninstall SMBstack, download the updated repository, enter the folder and run:
Para actualizar o desinstalar SMBstack, descarga el repositorio actualizado, entra a la carpeta y ejecuta:
cd smbstack
sudo bash smbinstall.sh --update
# or | o
sudo bash smbinstall.sh --uninstall
File
--update
--uninstall
conf/smb.conf
⛔ not touched (user-customized)
✅ restored from .bak if it exists (only created when the installer overwrote a pre-existing smb.conf; on a fresh install, no .bak exists and smb.conf is left untouched)
conf/fullaudit.conf
⛔ not touched (user-customized)
✅ removed
web/smbweb.conf
⛔ not touched (user-customized)
✅ removed
web/index.php
✅ overwritten
✅ removed
web/smbaudit.html
✅ overwritten
✅ removed
web/smbapi.php
✅ overwritten
✅ removed
web/smbaudit-diagnostic.php
✅ overwritten
✅ removed
web/shared.php
✅ overwritten
✅ removed
web/manifest.json
✅ overwritten
✅ removed
web/sw.js
✅ overwritten
✅ removed
web/icon.svg
✅ overwritten
✅ removed
tools/smbload.sh
✅ overwritten
✅ removed
tools/smbwatch.sh
✅ overwritten
✅ removed
/var/www/smbstack/smbstack.env
⛔ preserved
✅ removed
Shared folder (/home/$local_user/shared/)
⛔ never touched
⛔ never touched
--update only refreshes application code (web PHP/HTML viewers and tools/*.sh). Configuration files deployed at install time (smb.conf, fullaudit.conf, smbweb.conf) are never overwritten by --update, since they may contain manual edits (custom shares, hosts allow, interfaces, etc.). To pick up changes to these files after an update, compare them manually against conf/ and web/smbweb.conf in the repository and apply changes by hand.
--update solo actualiza el código de la aplicación (visores web PHP/HTML y tools/*.sh). Los archivos de configuración desplegados en la instalación (smb.conf, fullaudit.conf, smbweb.conf) nunca son sobreescritos por --update, ya que pueden contener ediciones manuales (shares personalizados, hosts allow, interfaces, etc.). Para incorporar cambios en estos archivos tras una actualización, compáralos manualmente contra conf/ y web/smbweb.conf en el repositorio y aplica los cambios a mano.
The shared folder is independent of the installer. To remove it, do so manually: rm -rf /home/$local_user/shared
La carpeta compartida es independiente del instalador. Para eliminarla, hazlo manualmente: rm -rf /home/$local_user/shared
Status
sudo bash smbinstall.sh --status
Shows: smbd and winbind service status, Apache port 3092, last 5 audit log entries, and testparm summary.
Config
After installation, the main configuration files are:
Tras la instalación, los archivos de configuración principales son:
Description
File
Samba main config
/etc/samba/smb.conf
Audit rsyslog rule
/etc/rsyslog.d/fullaudit.conf
Web vhost (audit + shared)
/etc/apache2/sites-available/smbweb.conf
Log rotation (Samba logs)
/etc/logrotate.d/samba
Log rotation (smbwatch.sh)
/etc/logrotate.d/smbwatch
Install config
/var/www/smbstack/smbstack.env
smbstack.env sets TRUSTED_PROXIES="127.0.0.1" by default. It tells web/shared.php to use the CF-Connecting-IP / X-Forwarded-For header (if present) instead of REMOTE_ADDR when logging the client IP for requests arriving from localhost — so a local tunnel's loopback connection isn't recorded as the "client" in the audit log. No effect on direct LAN access.
smbstack.env establece TRUSTED_PROXIES="127.0.0.1" por defecto. Le indica a web/shared.php que use el encabezado CF-Connecting-IP / X-Forwarded-For (si está presente) en lugar de REMOTE_ADDR al registrar la IP del cliente para solicitudes que lleguen desde localhost — así la conexión loopback de un túnel local no se registra como el "cliente" en el log de auditoría. Sin efecto en acceso LAN directo.
# Verify Samba config | Verificar configuración de Samba
testparm
# Restart services | Reiniciar servicios
sudo systemctl restart smbd winbind
# View audit log | Ver log de auditoría
tail -f /var/log/samba/log.audit
# List Samba users | Listar usuarios de Samba
sudo pdbedit -L
To use a custom shared folder path outside /home/$local_user/, edit /etc/samba/smb.conf and /etc/apache2/sites-available/smbweb.conf manually after installation.
Para usar una ruta de carpeta compartida personalizada fuera de /home/$local_user/, edita /etc/samba/smb.conf y /etc/apache2/sites-available/smbweb.conf manualmente tras la instalación.
Recycle Bin
SMBstack uses the Samba vfs_recycle module to redirect file deletions to a hidden recycle bin instead of permanently removing them. The bin is stored inside the shared folder under .recycle/.
SMBstack usa el módulo vfs_recycle de Samba para redirigir las eliminaciones a una papelera de reciclaje oculta en lugar de borrar permanentemente los archivos. La papelera se almacena dentro de la carpeta compartida en .recycle/.
Recycle bin channels
SMBstack writes to the recycle bin through three independent channels, each operating under a different system context:
SMBstack escribe en la papelera de reciclaje a través de tres canales independientes, cada uno operando bajo un contexto de sistema diferente:
Path
Written by
Purpose
.recycle/smbguest/
SMB clients on the LAN, through vfs_recycle (smbguest, set by force user in smb.conf)
Holds files deleted by users from Windows or Linux over the network / Guarda los archivos borrados por los usuarios desde Windows o Linux por la red
.recycle/www-data/
The web interface running under Apache (www-data)
Holds files deleted from the browser panel / Guarda los archivos borrados desde el panel web
Holds files moved out automatically when a monitored folder exceeds its size limit / Guarda los archivos retirados automáticamente cuando una carpeta monitoreada supera su límite de tamaño
This is why the recycle bin directory contains one subdirectory per channel:
Por eso el directorio de la papelera contiene un subdirectorio por canal:
.recycle/
├── smbguest/ # Files deleted by Windows/Linux SMB clients on the LAN
│ └── DOCUMENTS/
│ ├── report.docx
│ └── Copy #1 of report.docx
├── www-data/ # Files deleted via the web browser interface
│ └── 20260623/
│ └── invoice.pdf
└── smbwatch/ # Files auto-moved by the size-limit watchdog
└── 20260711/
└── bigfile.iso
Note: the recycle bin lives inside the shared folder itself so that recycling a file is a mv within the same filesystem — instantaneous and without copying data, which would not be the case if the bin were on another disk. For the details of each channel, see the Web Interface, smbwatch and Configuration reference sections.
Nota: la papelera vive dentro de la propia carpeta compartida para que reciclar un archivo sea un mv dentro del mismo sistema de archivos — instantáneo y sin copiar datos, cosa que no ocurriría si la papelera estuviera en otro disco. Para el detalle de cada canal, consulta las secciones Web Interface, smbwatch y Configuration reference.
Recycle timestamp
The weekly cleanup decides what to delete by reading each item's modification date, so that date must reflect the moment the item was recycled — not the day the document was last edited. Otherwise an old file recycled today would already count as expired and disappear on the next run. Each channel stamps the item with the current date on its way into the bin:
La limpieza semanal decide qué borrar leyendo la fecha de modificación de cada elemento, así que esa fecha debe reflejar el momento en que se recicló, no el día en que se editó el documento por última vez. De lo contrario, un archivo antiguo reciclado hoy ya contaría como vencido y desaparecería en la siguiente pasada. Cada canal sella el elemento con la fecha actual al entrar en la papelera:
Channel
Stamped by
SMB (LAN clients)
recycle:touch = yes in smb.conf
Web interface (Apache)
recycle_touch() in web/shared.php, applied recursively so a recycled folder carries its contents
Size-limit watchdog
touch after the move, in tools/smbwatch.sh
A restored item therefore carries the date it was recycled, not its original one.
Por eso un elemento restaurado conserva la fecha en que fue reciclado, no la original.
File versioning
When recycle:versions = yes is active, deleting a file that already exists in the recycle bin does not overwrite it — the new copy is saved alongside the original with a Copy #N of prefix:
Cuando recycle:versions = yes está activo, eliminar un archivo que ya existe en la papelera no lo sobreescribe — la nueva copia se guarda junto a la original con el prefijo Copy #N of:
.recycle/smbguest/DOCUMENTS/
├── report.docx ← first deletion
└── Copy #1 of report.docx ← second deletion of the same file
To exclude specific file types from versioning, use recycle:noversions. These types are still recycled, but repeated deletions overwrite the previous copy in the bin rather than creating a numbered duplicate:
Para excluir tipos de archivo del versionado, usa recycle:noversions. Estos archivos siguen yendo a la papelera, pero eliminaciones repetidas sobreescriben la copia anterior en lugar de crear una nueva numerada:
# All files keep multiple versions:
recycle:versions = yes
# These types are recycled but NOT versioned — second delete overwrites the first:
recycle:noversions = *.dat,*.ini
Use noversions for files where accumulating copies adds no value: runtime data files, config dumps, ini snapshots, and similar.
Usa noversions para archivos donde acumular copias no aporta valor: archivos de datos en tiempo de ejecución, volcados de configuración, snapshots de ini y similares.
Configuration reference
Parameter
Value
Purpose
recycle:repository
.recycle/%U
SMB channel recycle bin, resolves to smbguest / Papelera del canal SMB, resuelve a smbguest
recycle:directory_mode
0775
Group-writable recycle directory / Directorio escribible por el grupo
recycle:keeptree
yes
Preserve original folder structure / Preservar estructura de carpetas
recycle:versions
yes
Keep multiple versions of deleted files / Mantener múltiples versiones
recycle:noversions
*.dat,*.ini
Exclude patterns from versioning / Excluir patrones del versionado
recycle:touch
yes
Update access time when recycled / Actualizar tiempo de acceso al reciclar
The job runs once a week, so an item stays in the bin between 7 and 13 days depending on the day it was recycled.
La tarea corre una vez por semana, así que un elemento permanece en la papelera entre 7 y 13 días según el día en que se recicló.
To adjust the retention period or inspect the entry:
Para ajustar el período de retención o inspeccionar la entrada:
sudo crontab -e
Full Audit
SMBstack uses the Samba vfs_full_audit module to log file operations to /var/log/samba/log.audit via rsyslog. Only successful operations are recorded; failures are suppressed to keep the log clean.
SMBstack usa el módulo vfs_full_audit de Samba para registrar operaciones de archivos en /var/log/samba/log.audit vía rsyslog. Solo se registran operaciones exitosas; los fallos se suprimen para mantener el log limpio.
Configuration reference
Parameter
Value
Description
Descripción
full_audit:logfile
/var/log/samba/log.audit
Destination log file, written via the rsyslog rule in /etc/rsyslog.d/fullaudit.conf.
Archivo de log de destino, escrito mediante la regla rsyslog en /etc/rsyslog.d/fullaudit.conf.
full_audit:prefix
%I|%m|%S
Fields prepended to each log entry: %I = client IP address, %m = client machine name, %S = share name.
Campos que se anteponen a cada entrada del log: %I = IP del cliente, %m = nombre del equipo cliente, %S = nombre del share.
full_audit:success
mkdirat renameat unlinkat pwrite
VFS operations logged when they succeed. See table below.
Operaciones VFS que se registran cuando tienen éxito. Ver tabla a continuación.
full_audit:failure
none
No failed operations are logged.
No se registran operaciones fallidas.
full_audit:facility
LOCAL5
rsyslog facility used to route audit entries to the dedicated log file, keeping them separate from general system logs.
Facility de rsyslog usada para enrutar las entradas de auditoría al archivo dedicado, manteniéndolas separadas de los logs generales del sistema.
full_audit:priority
notice
Syslog priority level assigned to audit entries.
Nivel de prioridad syslog asignado a las entradas de auditoría.
Logged operations
Samba syscall
Triggered by
Desencadenado por
mkdirat
Creating a directory via SMB or the web interface
Creación de un directorio vía SMB o la interfaz web
renameat
Renaming or moving a file or folder. Also triggered by Windows clients when saving a file (temp file + rename pattern).
Renombrado o movimiento de archivo o carpeta. También lo disparan los clientes Windows al guardar un archivo (patrón de archivo temporal + renombrado).
unlinkat
File deletion — permanent or moved to the recycle bin. See caveat below.
Borrado de archivo — permanente o movido a la papelera. Ver matiz abajo.
pwrite
Data written to an open file, via SMB or via the web interface. See caveat below.
Datos escritos en un archivo abierto, vía SMB o vía la interfaz web. Ver matiz abajo.
Caveats
renameat log format: logged as source_path|destination_path. Does not appear for recycle bin operations.
Recycled vs. permanently deleted:unlinkat cannot tell them apart — vfs_full_audit intercepts the call before vfs_recycle redirects it. Check the .recycle/ directory on disk to know which happened.
pwrite source: logged both by Samba (SMB clients) and by shared.php (web uploads, which never go through smbd). To tell them apart, check the syslog $user field before smbd_audit: — the web interface always logs as www-data.
Formato de log de renameat: se registra como ruta_origen|ruta_destino. No aparece para operaciones de papelera de reciclaje.
Reciclado vs. eliminado permanente:unlinkat no puede distinguirlos — vfs_full_audit intercepta la llamada antes de que vfs_recycle la redirija. Revisa el directorio .recycle/ en el sistema de archivos para saber cuál ocurrió.
Origen de pwrite: lo registran tanto Samba (clientes SMB) como shared.php (subidas web, que nunca pasan por smbd). Para distinguirlas, revisa el campo $user del syslog antes de smbd_audit: — la interfaz web siempre lo registra como www-data.
Why openat is not audited
Evaluated and deliberately left out of full_audit:success by default. Every file/directory open — including plain browsing, reads and downloads, not just writes — generates an entry, so a single Explorer window left open on a busy folder produces dozens of near-duplicate lines per second. That noise buries the events actually worth reviewing without adding meaningful traceability, since pwrite already covers the write itself.
This is a project default, not a hard limitation. To audit opens/reads too, add it yourself in /etc/samba/smb.conf:
Then run testparm and systemctl restart smbd. --update won't touch this — smb.conf is never overwritten after install, so the change persists.
Se evaluó y se dejó fuera de full_audit:success por defecto, a propósito. Cada apertura de archivo o carpeta — incluyendo simple navegación, lecturas y descargas, no solo escrituras — genera una entrada, así que una sola ventana del Explorador abierta sobre una carpeta con actividad produce decenas de líneas casi idénticas por segundo. Ese ruido entierra los eventos que sí vale la pena revisar sin aportar trazabilidad real, ya que pwrite ya cubre la escritura en sí.
Esto es un valor por defecto del proyecto, no una limitación forzosa. Para auditar también aperturas/lecturas, agrégalo tú mismo en /etc/samba/smb.conf:
Luego ejecuta testparm y systemctl restart smbd. --update no lo tocará — smb.conf nunca se sobreescribe tras la instalación, así que el cambio persiste.
smbload
smbload.sh is a service watchdog that ensures smbd and winbind are running. Neither unit ships a Restart= policy, so nothing else brings them back once they stop. It also restarts smbwatch.sh if it is no longer running. It is automatically registered in cron every 5 minutes during installation and runs from /var/www/smbstack/tools/.
smbload.sh es un watchdog de servicios que garantiza que smbd y winbind estén en ejecución. Ninguna de las dos unidades trae política Restart=, así que nadie más las levanta cuando se detienen. También reinicia smbwatch.sh si ha dejado de ejecutarse. Se registra automáticamente en cron cada 5 minutos durante la instalación y corre desde /var/www/smbstack/tools/.
Note: the smbwatch check is inert until WATCH_LIMIT_GB and WATCH_EXCLUDE exist and are valid in smbstack.env, which happens the first time smbwatch.sh start is run from a terminal and its questions are answered. Until then smbload.sh logs a -- skip line and does not launch it.
Nota: la vigilancia de smbwatch permanece inactiva hasta que WATCH_LIMIT_GB y WATCH_EXCLUDE existan y sean válidas en smbstack.env, lo que ocurre la primera vez que se ejecuta smbwatch.sh start desde un terminal y se responden sus preguntas. Hasta entonces smbload.sh registra una línea -- skip y no lo lanza.
smbwatch
smbwatch.sh monitors first-level subdirectories of the shared folder in real time using inotifywait. When a subdirectory exceeds the configured size limit, the triggering file is automatically moved to .recycle/smbwatch/<YYYYMMDD>/ — its own channel, separate from .recycle/smbguest/ and .recycle/www-data/ (see Recycle bin channels). It is self-managed and independent of the installer — it reads its configuration from smbstack.env and prompts for any missing values, which requires a terminal: if a value is missing and there is none (for example under cron), it aborts instead of waiting for an answer.
smbwatch.sh monitorea en tiempo real las subcarpetas de primer nivel de la carpeta compartida usando inotifywait. Cuando una subcarpeta supera el límite de tamaño configurado, el archivo que disparó el evento se mueve automáticamente a .recycle/smbwatch/<YYYYMMDD>/ — su propio canal, separado de .recycle/smbguest/ y .recycle/www-data/ (ver Recycle bin channels). Es autogestionado e independiente del instalador — lee su configuración desde smbstack.env y solicita los valores faltantes, lo que exige un terminal: si falta un valor y no lo hay (por ejemplo bajo cron), aborta en lugar de quedarse esperando respuesta.
smbstack.env variable
Default
Purpose
WATCH_LIMIT_GB
10
Size limit per monitored folder, in GB / Límite de tamaño por carpeta monitoreada, en GB
WATCH_EXCLUDE
NONE
Comma-separated folder names excluded from monitoring (e.g. FINANCE,LEGAL) / Nombres de carpetas separados por comas excluidas del monitoreo
# Start
sudo /var/www/smbstack/tools/smbwatch.sh start
# Stop
sudo /var/www/smbstack/tools/smbwatch.sh stop
# Status
sudo /var/www/smbstack/tools/smbwatch.sh status
The list of monitored folders is built once, at startup. First-level folders can only be created by the administrator from the server shell — SMB clients and the web panel are both blocked at the share root — so after adding one, restart smbwatch (stop then start) for it to be monitored.
La lista de carpetas monitoreadas se arma una sola vez, al arrancar. Las carpetas de primer nivel solo puede crearlas el administrador desde el shell del servidor — los clientes SMB y el panel web están bloqueados en la raíz de la compartida — así que tras agregar una, reinicia smbwatch (stop y luego start) para que quede monitoreada.
NetBIOS
NetBIOS is a legacy protocol with documented security limitations, including unauthenticated name resolution and susceptibility to spoofing/poisoning attacks (e.g., NBT-NS and LLMNR poisoning). Consequently, it is disabled by default (disable netbios = yes in smb.conf), and the installer does not provide an option to enable it. Environments requiring compatibility with legacy Windows clients must enable NetBIOS manually after installation.
NetBIOS es un protocolo legado con limitaciones de seguridad ampliamente documentadas, entre ellas la resolución de nombres sin autenticación y la susceptibilidad a ataques de suplantación o envenenamiento (por ejemplo, NBT-NS y LLMNR poisoning). En consecuencia, permanece deshabilitado de forma predeterminada (disable netbios = yes en smb.conf) y el instalador no ofrece una opción para habilitarlo. Los entornos que requieran compatibilidad con clientes Windows legados deberán habilitar NetBIOS manualmente después de la instalación.
# Enable NetBIOS in smb.conf
sudo sed -i 's/^\s*disable netbios\s*=.*/ disable netbios = no/' /etc/samba/smb.conf
sudo sed -i "s/^;\s*netbios name\s*=.*/ netbios name = YOUR_HOSTNAME/" /etc/samba/smb.conf
# Start nmbd
sudo systemctl enable --now nmbd.service
sudo systemctl restart smbd
# Open the required ports (adjust IFACE to your Samba interface)
sudo iptables -A INPUT -i IFACE -p udp -m multiport --dports 137,138 -j ACCEPT
sudo iptables -A FORWARD -i IFACE -p udp -m multiport --dports 137,138 -j ACCEPT
sudo iptables -A INPUT -i IFACE -p tcp --dport 139 -j ACCEPT
sudo iptables -A FORWARD -i IFACE -p tcp --dport 139 -j ACCEPT
# Optional: rotate nmbd's log
sudo tee -a /etc/logrotate.d/samba > /dev/null <<'EOF'/var/log/samba/log.nmbd { weekly missingok rotate 7 postrotate systemctl reload nmbd 2>/dev/null || true endscript compress notifempty}EOF
⚠️ WARNING: NETWORK ACCESS
This project is designed to run locally and be accessed over a LAN. It is not recommended to expose it to the internet, as it lacks the hardening required for public-facing deployments.
If you choose to publish it despite this warning, it is strongly recommended to do so through an on-demand tunnel rather than opening ports directly. This approach lets you start and stop public access at will, without permanently exposing your server.
Este proyecto está diseñado para ejecutarse localmente y ser accedido en red LAN. No se recomienda exponerlo a internet, ya que no cuenta con el endurecimiento necesario para despliegues públicos.
Si decide publicarlo a pesar de esta advertencia, se recomienda hacerlo a través de un túnel bajo demanda en lugar de abrir puertos directamente. Este enfoque le permite iniciar y detener el acceso público a voluntad, sin exponer el servidor de forma permanente.
CSRF protection:web/shared.php has no login by design — guest access for the whole LAN (and the tunnel, if enabled) is intentional. What it does have is a per-session token on the four state-changing forms (upload, new folder, new file, recycle), so a POST is only accepted if it was actually loaded from the page first. This blocks a malicious site elsewhere from silently auto-submitting a form to your server through a visitor's browser (CSRF); it does not restrict who can use the browser itself — that's still governed purely by network reachability (LAN / tunnel), same as today.
Protección CSRF:web/shared.php no tiene login por diseño — el acceso de invitado para toda la LAN (y el túnel, si está activo) es intencional. Lo que sí tiene es un token por sesión en los cuatro formularios que modifican estado (subir, nueva carpeta, nuevo archivo, papelera), de modo que un POST solo se acepta si realmente se cargó la página antes. Esto bloquea que un sitio malicioso ajeno autoenvíe un formulario a tu servidor a través del navegador de un visitante (CSRF); no restringe quién puede usar el explorador en sí — eso sigue gobernado únicamente por el alcance de red (LAN / túnel), igual que hoy.
Folder size display: the total size shown for the folder being browsed in web/shared.php is cached for 30 seconds per path, to avoid re-walking a potentially large subtree on every page load. This means the number can lag up to 30 seconds behind the real content — purely cosmetic, since quota enforcement is handled independently by smbwatch.sh's own size checks, not by this display value.
Tamaño de carpeta mostrado: el tamaño total mostrado para la carpeta que se está navegando en web/shared.php se cachea por 30 segundos por ruta, para evitar recorrer un subárbol potencialmente grande en cada carga de página. Esto significa que el número puede quedar hasta 30 segundos desactualizado respecto al contenido real — es puramente cosmético, ya que el cumplimiento de la cuota lo maneja de forma independiente smbwatch.sh con sus propios chequeos de tamaño, no este valor mostrado.
Does not accept Pull Requests. Changes must be proposed via Issues.
Este repositorio
Puede incluir componentes de terceros.
No acepta Pull Requests. Los cambios deben proponerse mediante Issues.
SPONSOR THIS PROJECT
PROJECT LICENSES
This project uses a dual-licensing model to balance software freedom with content protection:
Este proyecto utiliza un modelo de licencia dual para equilibrar la libertad del software con la protección del contenido:
Content
Licensed Under
Scripts, Binaries, Infrastructure
RAG, Workers, Specialized Modules, Docs
DISCLAIMER
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
