necorouter

OverviewОбзор

necorouter turns a Linux machine into a router that is managed with commands in a familiar syntax. The configuration is written in the CLI, saved to a file and applied to the system: addresses, routes, NAT, DHCP, NTP, OSPF, VLANs, GRE tunnels.necorouter превращает Linux-машину в маршрутизатор, которым управляют командами в привычном синтаксисе. Конфигурация пишется в CLI, сохраняется в файл и применяется к системе: адреса, маршруты, NAT, DHCP, NTP, OSPF, VLAN, GRE-туннели.

What happens when you enter a commandЧто происходит при вводе команды

The command is parsed against the mode's tree, checked, applied to the in-memory configuration, and then the services are brought into line (reconcile). If the command did not change the configuration, nothing is restarted. The write commands save it to startup-config, and at the next daemon start it is replayed back.Команда разбирается по дереву режима, проверяется, применяется к конфигурации в памяти, а затем службы приводятся в соответствие (reconcile). Если команда не изменила конфигурацию, ничего не перезапускается. Команды write сохраняют её в startup-config, и при следующем старте демона она проигрывается обратно.

System requirementsСистемные требования

An estimate, not measured under real load.Оценка, не замерено на реальной нагрузке.

• Alpine: a musl system on x86_64 or aarch64; armv7 and i386 are not supported. FRR is the largest package; without OSPF it can be skipped.Alpine: musl-система на x86_64 или aarch64; armv7 и i386 не поддерживаются. FRR — самый большой пакет; без OSPF его можно не ставить.
• Services (FRR, dnsmasq, chrony, nftables) start only when the configuration needs them.Службы (FRR, dnsmasq, chrony, nftables) запускаются только когда нужны конфигурации.
• Users: 1–5 accounts put no load on the system; dozens cause no noticeable load; hundreds work, but applying the configuration reads /etc/passwd for every user.Пользователи: 1–5 учёток не нагружают систему; десятки — без заметной нагрузки; сотни работают, но применение конфигурации читает /etc/passwd для каждого пользователя.
• The daemon accepts up to 64 simultaneous sessions.Одновременных сессий демон принимает до 64.

InstallationУстановка

Root rights are required. By default the installer downloads the latest stable GitHub release, checks it against SHA256SUMS, installs the dependencies itself where possible (openssh-server, nftables, dnsmasq, frr, chrony), and enables the service. It installs required packages but does not upgrade the whole operating system.Нужны root-права. По умолчанию установщик скачивает последний стабильный релиз с GitHub, проверяет его по SHA256SUMS, по возможности ставит зависимости (openssh-server, nftables, dnsmasq, frr, chrony) и включает службу. Он ставит нужные пакеты, но не обновляет всю ОС.

make all                                   # builds dist/necorouter-x86_64 and dist/necorouter-aarch64
sh packaging/install.sh --bin dist/necorouter-x86_64
systemctl enable --now necorouter        # Alpine: rc-update add necorouter default && rc-service necorouter start

sh packaging/install.sh --uninstall      # removes the router and its accounts, restores /etc/issue and sshd_config

What the installer doesЧто делает установщик

• By default downloads the latest stable GitHub release and verifies its SHA256 checksum. Downloads use curl, wget, BusyBox wget or Python 3; if none is available, curl is installed through the package manager when dependencies are enabled.По умолчанию скачивает последний стабильный релиз GitHub и проверяет SHA256. Для загрузки используются curl, wget, wget из BusyBox или Python 3; если их нет, curl устанавливается пакетным менеджером, когда установка зависимостей включена.
• The checksum file comes from the same release, so it detects transfer damage but is not a separate release signature. Package signatures are checked according to the system package manager's repository configuration.Файл контрольных сумм скачивается из того же релиза: он выявляет повреждение загрузки, но не является отдельной подписью релиза. Подписи пакетов проверяются согласно настройкам репозиториев системного пакетного менеджера.
• Selects a binary from --bin, --local, or the default release download; builds from source only with --build.Выбирает бинарник через --bin, --local или загрузку релиза по умолчанию; сборка из исходников выполняется только с --build.
• Detects the distribution and the init system (systemd or OpenRC) and installs the service.Определяет дистрибутив и систему инициализации (systemd или OpenRC) и ставит службу.
• Creates the required links: /usr/local/bin/necorouter, /usr/bin/necorouter (for sudo's secure_path), necorouter-shell.Кладёт необходимые ссылки: /usr/local/bin/necorouter, /usr/bin/necorouter (для secure_path sudo), necorouter-shell.
• Registers the necorouter-shell shell in /etc/shells and a restriction block in sshd_config (accounts in the necorouter group are denied port forwarding, agent forwarding and X11).Регистрирует оболочку necorouter-shell в /etc/shells и блок ограничений в sshd_config (аккаунтам группы necorouter запрещены проброс портов, агента и X11).
• Creates the banner /etc/necorouter/banner and writes it to /etc/issue for the console.Создаёт баннер /etc/necorouter/banner и записывает его в /etc/issue для консоли.
• On Alpine it generates the sshd host keys and enables sshd at boot.На Alpine генерирует host-ключи sshd и включает sshd в автозагрузку.

Login and rolesВход и роли

Login is handled by plain Linux: login on the console and sshd over ssh. The password is checked by PAM. Rights inside the CLI come from the role in the daemon's configuration.Вход выполняет штатный Linux: login на консоли и sshd по ssh. Пароль проверяет PAM. Права внутри CLI задаёт роль из конфигурации демона.

AccountsУчётные записи

• username NAME in the configuration creates a Linux account with the router's shell and the necorouter group.username NAME в конфигурации создаёт Linux-аккаунт с оболочкой роутера и группой necorouter.
• The password is set with password PASS in the CLI (it changes the Linux account's password) or with passwd NAME in the system. The configuration holds no passwords.Пароль задаётся через password PASS в CLI (меняет пароль Linux-аккаунта) или командой passwd NAME в системе. В конфигурации паролей нет.
• Removing username from the configuration deletes the account the router created. Accounts that existed before the router are not deleted; they only get its shell.Удаление username из конфигурации удаляет созданный роутером аккаунт. Аккаунты, существовавшие до роутера, не удаляются, а только получают его оболочку.
• The router does not touch root and system accounts (uid < 1000): root keeps its normal shell and emergency login.root и системные аккаунты (uid < 1000) роутер не трогает: root сохраняет обычную оболочку и аварийный вход.

Pre-login bannerБаннер до входа

The banner from /etc/necorouter/banner is visible before login: on the console through /etc/issue (visible before root logs in too), over ssh through the Banner directive. The previous /etc/issue is saved and restored on removal. Your own ASCII art: put it in /etc/necorouter/banner and run necorouter issue sync.Баннер из /etc/necorouter/banner виден до логина: на консоли через /etc/issue (его видно и перед входом root), по ssh через директиву Banner. Прежний /etc/issue сохраняется и возвращается при удалении. Свой ASCII-арт: поместите его в /etc/necorouter/banner и выполните necorouter issue sync.

CLI modesРежимы CLI

The mode is shown in the prompt. Every mode is left with exit; to return to privileged mode use end or Ctrl-Z.Режим показан в приглашении. Из каждого режима выход — exit, возврат в привилегированный — end или Ctrl-Z.

FeaturesВозможности

Bufferbloat controlУстранение bufferbloat

For WAN bandwidth limits, create a service-policy, set bandwidth, then apply it to the WAN service-instance with direction in or out. The Linux backend uses CAKE; inbound traffic is redirected through IFB. Begin around 90–95% of measured sustained link speed. The kernel must provide sch_cake; iproute2 provides ip and tc.Задайте ограничения скорости WAN: создайте service-policy, задайте bandwidth, затем примените политику к WAN service-instance в направлении in или out. Linux backend использует CAKE; входящий трафик перенаправляется через IFB. Начните примерно с 90–95% устойчивой измеренной скорости. Ядро должно предоставлять sch_cake; iproute2 содержит команды ip и tc.

configure terminal
service-policy WAN-DOWN
 bandwidth mbps 95
exit
service-policy WAN-UP
 bandwidth mbps 9
exit
port te0
 service-instance wan
  encapsulation untagged
  connect ip interface wan
  service-policy WAN-DOWN in
  service-policy WAN-UP out
end
write
show service-policy

Configuration exampleПример конфигурации

enable
configure terminal
hostname example-1
ip domain-name example.local
username net_admin
 password P@ssw0rd
 role admin
 exit
port te1
 service-instance te1/isp
  encapsulation untagged
  exit
 exit
interface isp
 ip address 172.16.1.2/28
 connect port te1 service-instance te1/isp
 exit
ip route 0.0.0.0/0 172.16.1.1
ip nat pool server-pool 192.168.100.1-192.168.100.30
ip nat source dynamic inside-to-outside pool server-pool overload 172.16.1.2
router ospf 1
 network 10.10.10.0/30 area 0
 exit
ntp server 172.16.1.1
ntp timezone utc+3
end
write

A complete example configuration is in the README.Полный пример конфигурации — в README.

Command referenceСправочник команд

The tree is built from the same command table as the CLI itself, so it matches what ? shows. Pick a mode, expand the branches or use search. The "copy" button takes the command path with argument placeholders. Command descriptions come from the program and are in English.Дерево построено из той же таблицы команд, что и сам CLI, поэтому совпадает с тем, что показывает ?. Выберите режим, раскройте ветки или воспользуйтесь поиском. Кнопка «копировать» берёт путь команды с шаблонами аргументов. Описания команд берутся из программы и приведены на английском.

Keys and pagerКлавиши и пейджер

Line editorРедактор строки

Paged outputПостраничный вывод

Long output of show commands opens page by page (like less) when the terminal is small enough. Short output is printed at once. Through ssh host "command" and in scripts the pager is not used.Длинный вывод команд show открывается постранично (как less), если терминал достаточно мал. Короткий вывод печатается сразу. Через ssh host "команда" и в скриптах пейджер не используется.

The terminal length N command sets the number of lines per page, terminal length 0 turns the pager off.Команда terminal length N задаёт число строк на страницу, terminal length 0 отключает пейджер.

Configuration and filesКонфигурация и файлы

SavingСохранение

• An unsaved configuration lives in the daemon's memory and is already applied to the system. Logging out does not roll it back, and every session sees it. Save it with write; otherwise a daemon restart returns the configuration to startup-config.Несохранённая конфигурация живёт в памяти демона и уже применена к системе. Выход из учётки её не откатывает, и её видят все сессии. Сохраните командой write; иначе при перезапуске демона конфигурация вернётся к startup-config.
• write or copy running-config startup-config — save the current configuration.write или copy running-config startup-config — сохранить текущую конфигурацию.
• show running-config — what is in effect now; show startup-config — what is saved.show running-config — то, что действует сейчас; show startup-config — то, что сохранено.
• Crash copy. If the daemon terminated abnormally, at start running-config from the last snapshot is saved to crash-config and startup-config is left unchanged. The admin sees a warning at login; read it with show config file crash.Аварийная копия. Если демон завершился не штатно, при старте running-config из последнего снимка сохраняется в crash-config, а startup-config не меняется. Админ видит предупреждение при входе; читать: show config file crash.
• Baseline file commands: write file NAME, write terminal, show files config, show config file NAME, copy file NAME startup-config (with a warning).Ванильные команды файлов: write file NAME, write terminal, show files config, show config file NAME, copy file NAME startup-config (с предупреждением).
• startup-config archives: copy startup-config storage [description TEXT], show backups, delete backup storage NAME|*; files /etc/necorouter/backups/startup_backup_NAME_YYYY-MM-DD_hh-mm-ss.tar.gz. Ctrl-D on an empty line works as exit: it leaves a mode one level up, and the shell only from the base level.Архивы startup-config: copy startup-config storage [description TEXT], show backups, delete backup storage NAME|*; файлы /etc/necorouter/backups/startup_backup_ИМЯ_ГГГГ-ММ-ДД_чч-мм-сс.tar.gz. Ctrl-D на пустой строке работает как exit: из режима на уровень выше, из оболочки — только с базового уровня.
• Copying over SSH (the system scp/sftp): copy startup-config scp|sftp USER@HOST[:PATH] — send a startup-config archive; copy scp|sftp backup NAME USER@HOST[:PATH] — an archive from storage; copy scp|sftp startup-config USER@HOST:FILE — receive an archive or a plain configuration file (checking, warning, confirmation). An empty path or a path ending in / is a directory (the home directory by default). The password is asked without echo (empty input means only root's keys from ~/.ssh), passed through SSH_ASKPASS and not stored. A new host key is remembered in /var/lib/necorouter/known_hosts, a changed one is refused.Копирование по SSH (системные scp/sftp): copy startup-config scp|sftp USER@HOST[:ПУТЬ] — отправить архив startup-config; copy scp|sftp backup ИМЯ USER@HOST[:ПУТЬ] — архив из хранилища; copy scp|sftp startup-config USER@HOST:ФАЙЛ — принять архив или обычный файл конфигурации (проверка, предупреждение, подтверждение). Пустой путь или путь на / — каталог (по умолчанию домашний). Пароль спрашивается без эха (пустой ввод — только ключи root из ~/.ssh), передаётся через SSH_ASKPASS и не хранится. Новый ключ хоста запоминается в /var/lib/necorouter/known_hosts, изменившийся — отказ.
• Security profiles: security-profile N → rule 0 permit|deny PROTO SRC DST [eq|gt|lt|range PORT], no rule N; security N / security none / no security; show security-profile. The default profile is on by default and closes SSH, Telnet and SNMP on the router's interfaces; remove it with no security default. Established connections are not dropped, network cards outside the router configuration are not affected. A bound profile cannot be changed — run no security first. Implemented in nftables (table ip necorouter_sec).Профили безопасности: security-profile N → rule 0 permit|deny PROTO SRC DST [eq|gt|lt|range PORT], no rule N; security N / security none / no security; show security-profile. Профиль default включён по умолчанию и закрывает SSH, Telnet и SNMP на интерфейсах роутера; снять: no security default. Установленные соединения не обрываются, сетевые карты вне конфигурации роутера не затрагиваются. Привязанный профиль менять нельзя — сначала no security. Реализовано в nftables (table ip necorouter_sec).
• enable password: enable password PASS or enable secret PASS (up to 8 Latin letters and digits, starting with a letter); enable asks for the password without echo, no enable password removes it. Only a hash is stored in the configuration (enable password 8 HASH, a custom format, not DES). The local root is not asked for a password.Пароль enable: enable password PASS или enable secret PASS (до 8 латинских букв и цифр, с буквы); enable спрашивает пароль без эха, no enable password снимает. В конфигурации хранится только хеш (enable password 8 ХЕШ, свой формат, не DES). Локальный root пароль не спрашивается.
• Autosave is off by default. Enable it with autosave interval MIN through feature config-history (5 minutes by default, only when there are changes, into the autosave history); no autosave turns it off. feature ssh-copy — copying over scp/sftp (non-baseline syntax); show features — the state of the features. service password-encryption is a baseline command; passwords are stored as hashes anyway.Автосейв выключен по умолчанию. Включается командой autosave interval MIN через feature config-history (по умолчанию 5 минут, только при изменениях, в историю автокопий); no autosave выключает его. feature ssh-copy — копирование по scp/sftp (неванильный синтаксис); show features — состояние фич. service password-encryption — ванильная команда, пароли и так хранятся хешами.
• Extensions are hidden (not shown by ?) until they are enabled with the feature command in configuration mode: feature config-history — startup-config history (startup-history keep N), running-config autosaves (autosave interval MIN [keep N], no autosave), write description TEXT, show config history; feature config-manage — copy between files and into running-config (checking, a warning, protection against losing access), delete config file NAME, show config diff A B; feature config-journal — show config journal [N]. no feature ... turns a function off; settings and files remain. keep: 1–64, 10 by default. Priority: running → crash → startup → history → files; the history is never loaded by itself.Расширения скрыты (не видны в ?), пока не включены командой feature в режиме конфигурации: feature config-history — история startup-config (startup-history keep N), автокопии running-config (autosave interval MIN [keep N], no autosave), write description TEXT, show config history; feature config-manage — copy между файлами и в running-config (проверка, предупреждение, защита от потери доступа), delete config file NAME, show config diff A B; feature config-journal — show config journal [N]. no feature ... отключает функцию, настройки и файлы остаются. keep: 1–64, по умолчанию 10. Приоритет: running → crash → startup → история → файлы; история сама не загружается.
• An old password line in startup-config is applied once, when the account is created, and is not written again.Старая строка password в startup-config применяется один раз, при создании аккаунта, и больше не записывается.

AdvantagesПреимущества

• Runs on ordinary Linux: no device-specific OS is needed; routing and services are proven daemons (FRR, dnsmasq, chrony, nftables, strongSwan).Работает на обычном Linux: не нужна собственная ОС устройства; маршрутизация и сервисы — проверенные демоны (FRR, dnsmasq, chrony, nftables, strongSwan).
• teN ports are mapped to network cards through ports.map, so interfaces can be assigned to fit a lab setup.Порты teN сопоставляются сетевым картам через ports.map, интерфейсы можно назначать под стенд.
• Login and passwords are ordinary Linux accounts; there is no separate user database.Вход и пароли — обычные Linux-аккаунты, отдельной базы пользователей нет.
• The commands cover what is needed for practice and exams; anything non-standard is enabled explicitly through feature.Команды покрывают нужное для практики и экзаменов; нестандартное включается явно через feature.
• The event log and the audit of user actions are kept by the router itself, independent of journald or syslog, and work the same on systemd and OpenRC.Журнал событий и аудит действий пользователей ведутся самим роутером, не зависят от journald или syslog и одинаково работают на systemd и OpenRC.

LimitationsОграничения

What has already been checked automatically and what remains to be checked on the target systems.Что уже проверено автоматически и что остаётся проверить на целевых системах.

TroubleshootingУстранение неполадок

TestingТестирование

The full set is run with make test (root and unshare are required). Running the interactive tests from a namespace without a network: unshare -n -u -m python3 test/pty_cli.py.Полный набор запускается командой make test (нужны root и unshare). Запуск интерактивных тестов из пространства имён без сети: unshare -n -u -m python3 test/pty_cli.py.