Seri portları (COM / ttyUSB / ttyACM / ttyS) ağ üzerinden erişilebilir kılan, web arayüzünden yönetilen, çapraz-platform (Windows + Linux) saf-Python köprü.
C dünyasındaki
ser2net'in modern, web yönetimli karşılığı. Tek ekrandan onlarca seri portu IP:port'a eşleyin; raw / telnet / RFC2217; çift yönlü; düşük gecikme.
Pano — onlarca eşleme, canlı durum, algılanan portlar ve LAN cluster paneli:
LAN cluster — tüm düğümlerin eşlemeleri tek tabloda; düğüm sağlığı + uzaktan başlat/durdur:
| Eşleme ekleme (tüm seri/ağ seçenekleri) | Tarayıcı-içi seri konsol (xterm.js) |
|---|---|
 |
 |
| Ayarlar (parola · TLS · cluster · yedek) | Giriş |
|---|---|
 |
 |
Endüstriyel cihazlar, PLC'ler, ölçüm aletleri, GPS/modem, mikrodenetleyiciler ve
konsol portları çoğunlukla seri (RS-232/485/USB-serial) haberleşir. Bu cihazlara
ağdaki herhangi bir bilgisayardan erişmek için her seri portu bir TCP/UDP uç
noktasına köprülemek gerekir. ser2net bunu yapar ve tüm yönetimi parola
korumalı bir web arayüzünden sunar — komut satırı veya elle config dosyası
düzenlemeye gerek yok.
Tipik kullanım senaryoları:
- Bir sunucuya bağlı 10+ USB-serial cihazı ağdaki uygulamalara açmak
- SCADA / Modbus-RTU cihazlarını uzak istemcilere ulaştırmak (raw veya RFC2217)
- Cihaz konsollarına (switch, router, gömülü kart) ağdan erişim
- Uzak baud/parity değişimi gereken cihazlar için RFC2217
- İki seri portu birbirine köprüleme (serial↔serial)
- Taşıma modları: TCP sunucu (dinleme), TCP istemci (dışarı bağlanma), UDP, ve serial↔serial köprüleme. TCP köprüleri için isteğe bağlı TLS.
- Protokoller:
raw,telnet(8-bit temiz),rfc2217(uzaktan canlı baud/parity/databit/stopbit/akış kontrolü değişimi),modbus(RTU↔TCP gateway). - Modbus ağ geçidi: Modbus/TCP master'larını seri Modbus/RTU slave'lere köprüler —
çoklu master, paylaşımlı bus'ta transaction serileştirme + transaction-id koruması,
RTU yanıtı gelmezse
0x0B(gateway-timeout) exception. Edge modu: register'ları periyodik okuyup MQTT'ye yayınlar (uint/int/float 16/32, ölçek). - Client-side sanal COM: uzaktaki portu yerel
COMx/ttyolarak göstermek için reçeteler (pyserialrfc2217://, Linuxsocat, Windows com0com+com2tcp / HW VSP3) — bkz.docs/VIRTUAL-COM.md. - Tam seri yapılandırma: baud (custom dahil), data bit, parity, stop bit, akış
kontrolü (none/RTS-CTS/XON-XOFF/DSR-DTR), açılışta RTS/DTR, exclusive open ve RS-485
donanım auto-RTS (Linux
TIOCSRS485: aç + TX öncesi/sonrası gecikme + TX'te RTS seviyesi). - Canlı port listesi: ayrıcalık gerektirmeyen polling + isteğe bağlı olay-tabanlı hotplug (Linux pyudev / Windows WM_DEVICECHANGE), yoksa polling'e düşer.
- IP seçici: makineye atanmış IP'ler (localhost / LAN / 0.0.0.0) veya custom.
- Onlarca eşleme: tek ekrandan ekle/düzenle/sil/başlat/durdur, canlı durum.
- Erişim kontrolü (eşleme başına): izinli IP/CIDR listesi, yüksek-öncelikli
istemci IP'leri (doluyken eski istemciyi atar), max bağlantı, eski-kullanıcıyı-at,
salt-okunur, idle timeout, banner, open/close string,
closeon. - Gözlemlenebilirlik: per-mapping trafik trace (hex/timestamp), Prometheus
/metrics, config-değişiklik audit log, canlı log görüntüleyici, ve tarayıcı-içi seri konsol (xterm.js, WebSocket — trafiği izle veya cihaza yaz). - Güvenlik: parola (ilk erişimde belirlenir, scrypt), CSRF, imzalı-çerez oturum, login oran sınırı, sıkı güvenlik başlıkları, parola değişince oturum iptali.
- Çok-kullanıcı / RBAC:
admin/operator/viewerrolleri — viewer salt-okunur, operator eşlemeleri yönetir, admin her şey + kullanıcı yönetimi. Tek-parola kurulumları otomatik olarak biradminkullanıcısına geçer. - LDAP / Active Directory auth (opsiyonel): kullanıcılar dizine bind ederek doğrulanır;
LDAP grup üyeliği role eşlenir. Yerel hesaplarla birlikte çalışır;
ldap3gerektirir. - OIDC tek-oturum (SSO, opsiyonel): Keycloak/Entra ID/Google/Okta ile authorization-code
akışı; id_token doğrulanır (imza/iss/aud/exp/nonce), claim→rol eşlenir.
authlibgerektirir. - REST API: otomasyon için JSON API (
/api/v1) — eşleme CRUD, başlat/durdur/yeniden, durum ve portlar; bearer-token kimlik doğrulama (rol seçilebilir —viewersalt-okunur); OpenAPI 3.0 (/api/v1/openapi.json). Token, Ayarlar'dan üretilir. - LAN cluster (filo yönetimi): aynı ağdaki düğümler birbirini otomatik bulur (imzalı UDP broadcast — mDNS yok) ve bir düğüm tüm düğümlerin eşlemelerini tek tabloda gösterir; her satır hangi bilgisayara ait olduğunu (ad + IP) ve her düğümün sağlığını (uptime · sürüm · çalışan/toplam) belirtir. Operatörler bu ekrandan başka bir host'un eşlemelerini uzaktan başlat/durdur/yeniden başlat ve düzenle edebilir. Broadcast'in ulaşmadığı yönlendirilmiş/L3 ağlar için manuel peer (host:port) eklenebilir. Güven = her düğümde aynı paylaşılan anahtar; varsayılan kapalı, Ayarlar → LAN cluster'dan açılır.
- Dağıtım: resmi Docker imajı +
docker-compose; systemd birimi; Linux+Windows × Python 3.10–3.13 CI (GitHub Actions). - MQTT yayınlama (opsiyonel): seri satırlarını eşleme başına bir MQTT broker'ına
yayınlar (host/port/topic/QoS/TLS/kimlik), retained birth/death durumuyla.
paho-mqttgerektirir (opsiyonel; yoksa köprü normal çalışır). - Tamamen offline: tüm bağımlılıklar wheel olarak birlikte gelir; internet gerekmez.
- Python 3.10+ (sistemde kurulu). Başka hiçbir şey gerekmez — bağımlılıklar
vendor/wheels/içinde gelir ve ilk çalıştırmada./lib'e kurulur (offline). - Linux'ta seri portu açmak için kullanıcının
dialoutgrubunda olması gerekir (port listelemek için ayrıcalık gerekmez):sudo usermod -aG dialout "$USER" # ardından oturumu kapatıp aç
- Windows'ta COM portları için ek yetki gerekmez.
- (Opsiyonel) TLS self-signed üretimi için
openssl; olay-tabanlı hotplug içinpyudev(Linux) /pywin32(Windows) — yoksa polling kullanılır.
# Linux / macOS
python3 ser2net.py # veya: ./start.sh
# Windows
start.batHer sürümde Windows .exe ve Linux binary'si GitHub Releases'a eklenir (PyInstaller;
MQTT/LDAP/OIDC dahil bundle'lı). İndir, çalıştır — config/log data/ altında binary'nin
yanına yazılır. Kendin derlemek için: pip install pyinstaller && pyinstaller ser2net.spec.
İlk çalıştırmada:
- Konsolda arayüzün hangi IP'den erişileceği sorulur (makine IP'leri veya custom) ve port (varsayılan 8080). Başsız/servis ortamında güvenli varsayılan 127.0.0.1.
- Tarayıcıda açılan adrese gidin; ilk ekranda admin parolasını belirleyin.
- Panodan + Eşleme ekle ile COM/tty seçip IP:port'a eşleyin.
Bind IP'yi sonradan değiştirmek:
python3 ser2net.py --reconfigureBağımlılıklar vendor/wheels/ içinde bulunur; ser2net.py ilk açılışta bunları
./lib'e kurar (pip install --no-index). İnternet gerektirmez. Farklı Python
sürümü/işletim sistemi için ek wheel gerekirse:
python3 -m pip download -r requirements.txt -d vendor/wheels \
--platform win_amd64 --python-version 312 --only-binary=:all:Opsiyonel özellikleri (MQTT/LDAP/OIDC) offline kaynak kurulumunda etkinleştirmek için
wheel'lerini de indirip kurun: pip download paho-mqtt ldap3 authlib -d vendor/wheels
ardından pip install --no-index --find-links vendor/wheels paho-mqtt ldap3 authlib.
(Standalone binary bunları zaten içerir.)
docker compose up -d # docker-compose.yml içindeki `devices:` satırını düzenleyin
# veya:
docker build -t ser2net . && docker run -d -p 8080:8080 \
--device /dev/ttyUSB0 --group-add dialout -v ser2net-data:/data ser2netContainer'da arayüz 0.0.0.0'a bağlanır (SER2NET_BIND_IP / SER2NET_PORT env ile
ayarlanır — başsız ortamda interaktif seçici çalışamaz). Ayrıntılar:
docs/DOCKER.md.
- Eşleme ekle: Ad, tür (Serial↔Network / Serial↔Serial), seri port + parametreler, ağ modu (server/client/udp), protokol, bind/remote IP:port, erişim kuralları.
- Başlat/Durdur/Yeniden başlat/Kopyala/Sil: her satırda.
- Log: eşlemenin geçmiş logu (en yeni üstte, restart sonrası kalıcı).
- Monitor: tarayıcıda canlı seri terminal (xterm.js); ağ eşlemelerinde cihaza yazılabilir.
- Ayarlar: parola değiştir, admin TLS (yol ver veya self-signed üret), REST API token'ı üret/iptal et, mapping yedek al/yükle (JSON), durum.
- /metrics: Prometheus formatında metrikler (kimlik doğrulamalı).
Tarayıcı arayüzünün yanında, otomasyon için JSON bir API (/api/v1). Kimlik doğrulama
Authorization: Bearer <token> ile yapılır; token'ı Ayarlar → REST API token'dan
üretin (yalnızca bir kez gösterilir). Tam tanım: GET /api/v1/openapi.json.
TOKEN="s2n_..." # Ayarlar'dan üretilen token
# tüm eşlemeler (config + canlı durum)
curl -H "Authorization: Bearer $TOKEN" http://HOST:8080/api/v1/mappings
# eşleme oluştur
curl -X POST -H "Authorization: Bearer $TOKEN" -H "Content-Type: application/json" \
-d '{"name":"PLC-1","kind":"net","serial":{"port":"/dev/ttyUSB0","baudrate":9600},
"network":{"mode":"server","bind_ip":"0.0.0.0","port":4001}}' \
http://HOST:8080/api/v1/mappings
# başlat / durdur / yeniden başlat
curl -X POST -H "Authorization: Bearer $TOKEN" http://HOST:8080/api/v1/mappings/<id>/stopUç noktalar: GET/POST /mappings, GET/PUT/DELETE /mappings/{id},
POST /mappings/{id}/{start|stop|restart}, GET /status, GET /ports,
GET /health (kimlik doğrulamasız), GET /openapi.json.
Arayüz her zaman parola korumalı. Varsayılan bind 127.0.0.1; ağa açmak için
açılışta IP seçimi gerekir ve TLS'siz ağ bind'inde uyarı verilir. LAN'a açılan
kurulumlarda TLS (admin_ui.tls_*) ve eşleme bazlı allowed_client_ips önerilir.
Raw TCP düz-metindir — güvensiz ağlarda dikkat. Allowed/priority listesinde tek başına
0.0.0.0/:: "herkes" demektir.
- Docker: resmi
Dockerfile+docker-compose.yml(bkz. yukarısı vedocs/DOCKER.md) —restart: unless-stopped,/datavolume. - Linux (systemd):
systemd/ser2net.service— ayrı, yetkisiz bir kullanıcı,SupplementaryGroups=dialout,Restart=on-failure, sertleştirme direktifleri. root ile çalıştırmayın. - Windows: Shawl ile servis sarmalama.
Tüm durum veri dizininde (varsayılan data/). Veri dizini yalnızca sahibe açık
kilitlenir (POSIX 0700; Windows'ta icacls ile sahip/SYSTEM/Administrators), böylece
içindeki dosyalar başka kullanıcılarca okunamaz:
config.json— admin IP, parola hash'i, tüm eşlemeler (atomik yazım).all.log— global etkinlik/audit (boyutla döner);audit.log— config değişiklikleri (döner).logs/<id>.log— eşleme başına geçmiş (saatlik bakım: >15 gün veya >100MB kırpılır).tls/— self-signed üretilirse sertifika/anahtar.
config.json + all.log silinince sistem sıfırdan başlar (orphan loglar otomatik temizlenir).
Birleşik test koşucusu — taşınabilir (donanımsız, socat'sız) takım her işletim sisteminde çalışır:
python3 tests/run_all.py # taşınabilir takım (Windows + Linux)
python3 tests/run_all.py --socat # + socat tabanlı veri-yolu testleri (Linux)socat (Linux) ile sanal seri portlar kullanılır; donanım gerekmez. Tek tek de
çalıştırılabilir, örn. python3 tests/test_rest_api.py. CI (GitHub Actions) ruff
lint + tam matrisi (ubuntu/windows × Python 3.10–3.13) koşar.
Ticari/özel lisans — bkz. LICENSE. Yazara ait, tüm hakları saklıdır;
geçerli bir ticari lisans olmadan kullanım/dağıtım/satış yapılamaz. Birlikte gelen
üçüncü-taraf bileşenler kendi (izin-verici) lisanslarını korur — bkz.
THIRD-PARTY-NOTICES.md. İletişim: haliskilic90@gmail.com
Yol haritası: ROADMAP.md · English: README.en.md