Zorven dokümanları

Kurulum

Zorven istemcisi tek bir ikili dosyadır (zorven). Kurulum betikleri ikiliyi indirir, token'ını ve sunucu adresini sistem yapılandırmasına yazar ve arka plan servisini başlatır.

Linux ve macOS

Betik /usr/local/bin/zorven yolunu kullanır ve sistem servisi oluşturduğu için root yetkisi ister. Token'ı panelden al (Hızlı başlangıç) ve bayrakla ver:

Token vermezsen betik sorar. Çalıştırmadan önce betiği okumak istersen:

Windows

PowerShell'i Yönetici olarak aç. Betik C:\Program Files\Zorven altına kurar ve Windows servisini başlatır:

Betiği önce incelemek için irm https://zorven.app/install.ps1 çıktısını bir dosyaya yönlendirip oku.

Masaüstü uygulaması

Windows için grafik arayüzlü kurulum paketi: Zorven-Setup-windows-amd64.exe. Ayrıntılar ve diğer platformlar için İndir sayfasına bak.

Elle indirme

Betik kullanmak istemezsen ikiliyi doğrudan indir, çalıştırılabilir yap ve PATH üzerindeki bir dizine koy.

Güncel sürüm bilgisi /bin/manifest.json içindedir. İstemci kendini otomatik güncelleyebilir; kapatmak için --no-auto-update bayrağını kullan.

Hızlı başlangıç

1. Hesap aç ve token oluştur Panele gir, bir istemci oluştur ve zrv_live_ ile başlayan istemci token'ını kopyala. Token bir cihazın kimliğidir; gizli tut.
2. Token'ı kaydet
   $zorven authtoken zrv_live_...

   Kopyala
3. Yerel portunu yayınla
   $zorven http 3000

   Kopyala
   Çıktıdaki https://<ad>--slug.zorven.app adresi geçerli TLS ile hemen yayındadır; WebSocket, HTTP/2 ve SSE çalışır. İstemci bir durum kutusu basar: Durum: Cevrimici (Online), Genel URL: https://<ad>--slug.zorven.app, Yerel Hedef: http://localhost:3000.
4. Gerekirse geçici tünel aç
   $zorven ephemeral 3000 --ttl 30m

   Kopyala
   Süre dolunca tünel kendini siler. Başlangıçta Gecici tunel: 30m0s sonra kendiliginden kaldirilacak. satırı yazılır.

CLI komutları

Aşağıdaki liste istemcinin gerçek komutlarıdır. Her komutun yardımı için zorven <komut> --help çalıştırabilirsin.

zorven http <port> ve zorven <port>

Yerel bir HTTP servisini internete açar. zorven 8080 kısa yazımı da aynı işi yapar.

Uzak terminal ve ekran paylaşımı CLI ve servis modunda varsayılan olarak kapalıdır; Windows masaüstü uygulamasında varsayılan olarak açıktır. Panelden uzak terminal/ekran kullanmak için CLI'da bu cihazda açıkça izin ver (0.2.2 ve üzeri):

Panel terminali: İstemci makinedeki kabukları bildirir; panelde yeni sekme açarken bunlardan birini seçersin (bash, zsh, fish, sh, PowerShell 7, Windows PowerShell, cmd, WSL). Aynı istemcide en fazla 8 sekme açabilirsin; sekmelerde arama, yazı boyutu ve seçince kopyalama var. zsh ve bash, Zorven profiliyle (istem, otomatik öneri, sözdizimi vurgulama) açılır; düz kabuk için --terminal-plain-zsh / --terminal-plain-bash kullan. Kabuk sunucuda yaşar: başka sayfaya geçince ya da sayfayı yenileyince sekme aynı kabuğa geri bağlanır ve son çıktı yeniden gösterilir. Bağlantı koptuktan sonra kabuk 30 dakika bekler; sekmeyi kapatınca kabuk da kapanır. Oturuma yalnızca onu açan kişi geri bağlanabilir.

zorven ephemeral <port>

Süresi dolunca kendini silen geçici tünel açar; demo, webhook testi ve PR önizlemesi için uygundur. --ttl 1 dakika ile 24 saat arasında olmalı (varsayılan 2h). Kısa adlar: temp, tmp.

zorven authtoken <token>

İstemci token'ını yerel yapılandırmaya kaydeder. Token zrv_live_ ile başlamalıdır; aksi halde komut hata verir. Kısa ad: token.

status, update, version

İstemci sürümünü, ayar dosyasını, sunucu adresini, kayıtlı token'ı (maskeli) ve arka plan servisinin durumunu gösterir (sürüm satırı 0.2.2 ve üzeri).

Yeni sürüm varsa indirir ve uygular (istemci yeniden başlar).

İstemci ve protokol sürümünü, işletim sistemi ve mimariyi yazar. Destek talebinde bu çıktıyı ekle.

zorven config

--system bayrağı ayarı sistem geneline (servis moduna) yazar; yönetici/root yetkisi gerekir. Ayrıntı için Yapılandırma bölümüne bak.

zorven connect Team+

Zorven Network'e bağlanır ve yerel bir SOCKS5 proxy açar (varsayılan 127.0.0.1:1080). Uygulamaların, internete açılmamış özel kaynaklara (ör. db.internal:5432) adıyla ulaşır. Bu komut istemci token'ı değil, API token'ı ister (panelde API Anahtarları, en az tunnels:read kapsamı). Token bir servis hesabına ait olmalı ve o servis hesabına erişim veren bir kaynak politikası tanımlanmış olmalıdır (REST API: POST /resource-policies, grant.service_account_ids); politika yoksa bağlantı kaynaklara ulaşamaz.

Ardından uygulamanda SOCKS5 proxy olarak 127.0.0.1:1080 kullan. Örnek, SSH ile:

Ağ geçidi (site-to-site) modunda proxy'yi LAN'a açabilirsin; bu mod için izinli istemci aralıkları zorunludur:

zorven forward <host>

SNI modundaki bir ham TCP tüneline yerel bir port bağlar (ziyaretçi tarafı). Örneğin oyun sunucusuna bağlanmak için:

Ardından uygulamanı 127.0.0.1:25565 adresine bağla. Başka bir adreste dinlemek için --listen kullan. Bu komut yalnızca TCP'yi destekler; UDP için panelde ayrılmış port modunu kullan.

Ortak bayraklar

zorven, zorven http ve zorven ephemeral komutlarında kullanılabilir (0.2.2 ve üzeri; önceki sürümlerde bayraklar yalnızca zorven [port] komutundadır):

Servis modu

Servis modunda istemci oturum açmasan da arka planda çalışır ve bilgisayar açıldığında kendiliğinden başlar (Windows Service veya systemd). Kurulum betikleri bunu zaten yapar; elle kurmak için yönetici/root yetkisiyle:

Servis, kullanıcı ayarlarını değil sistem yapılandırmasını okur; bu yüzden token ve sunucuyu --system ile (veya service install --token ile) yazman gerekir. zorven authtoken tek başına servisi yapılandırmaz; servis için sudo zorven service install --token zrv_live_... kullan.

Yapılandırma

İstemci iki ayar dosyası kullanır: kullanıcıya ait config.json (kullanıcı yapılandırma dizinindeki zorven klasöründe) ve servis modu için sistem geneli dosya (Linux/macOS: /etc/zorven/config.json, Windows: %ProgramData%\zorven\config.json). Geçerli değerleri görmek için zorven config show çalıştır.

Ortam değişkenleri de desteklenir:

Sunucu adresi belirtilmezse varsayılan zorven.app:443 kullanılır. Kendi sunucunda çalıştırıyorsan zorven config set-server ile kendi adresini ver.

Panel kavramları

Yönetim panel.zorven.app üzerinden yapılır. Aşağıda kavramlar ve hangi plandan itibaren kullanılabildikleri özetlenir; güncel limitler için fiyatlandırma sayfasına bak.

Organizasyon ve projeler

Her hesap bir organizasyona bağlıdır. Tünelleri, istemcileri ve domainleri projeler altında gruplayabilirsin; böylece staging, üretim veya müşteri ortamları birbirine karışmaz. Proje sayısı plana göre değişir (Free 2, Hobby 3, Pro 10, Team 50).

Tüneller

Bir istemci (cihaz) bir veya daha fazla tünel açar. Tünel türleri: HTTP/HTTPS, ham TCP (veritabanı, SSH), SNI modlu TCP ve UDP (oyun sunucuları). HTTP tünellerinde yol tabanlı yönlendirme, trafik politikası ve panelde istek denetleyicisi (başlık/gövde görüntüleme ve tek tıkla yeniden gönderme) bulunur. Tünele parola (Basic Auth) veya Google/GitHub ile ziyaretçi girişi ekleyebilirsin. Capture ile kaydedilen istekleri yeniden gönderebilir (replay) ve iki yanıtı karşılaştırabilirsin (replay diff). İstek denetleyicisi, kimlik doğrulama, politika veya IP kuralı nedeniyle erken reddedilen istekleri (401, politika, IP) kaydetmez. Node ve Python SDK'ları da vardır.

Domainler

Her tünel ücretsiz kiracı adresi (ad--slug.zorven.app, slug organizasyonunun kısa adıdır) ve otomatik HTTPS alır. Panelde Domainler bölümünden ad.zorven.app biçiminde global bir kısa ad da alabilirsin (ilk gelen alır): Pro'da 1, Team'de 3, Enterprise'da 10 adet; Pro+. Plan düşerse kota dışında kalan kısa adlar ve özel domainler silinmez, askıya alınır (erişime kapanır); planı yükselttiğinde en eski adlardan başlayarak yeniden açılır. zorven ve rpshell içeren adlar alınamaz. Kendi alan adını (ör. api.sirketin.com) panelden ekleyip gösterilen DNS kayıtlarını (sahiplik doğrulaması ve CNAME) oluşturduğunda Zorven sertifikayı otomatik alır ve yeniler. Özel domain Hobby+ planlarda açılır.

Sertifikalar: *.zorven.app için platform joker (wildcard) sertifikası DNS doğrulamasıyla (acme.sh) sunucu dışında alınır ve dosyadan yüklenir; özel domainler için sertifika Let's Encrypt'ten otomatik alınır (HTTP-01 ve TLS-ALPN-01). DNS doğrulaması tamamlanmamış bir özel domainde TLS el sıkışması reddedilir.

Ekip

Organizasyona e-posta davetiyle üye ekle; roller owner, admin ve member'dır. Ekip sayfası Pro+ planlarda kullanılır; üye limiti plana göre değişir (Pro 3, Team 5). Kurumsal giriş için OIDC SSO ve 2FA desteklenir.

Policy ve Secret Vault

Policy motoru Pro+, kod yazmadan panelden kural tanımlamanı sağlar: rate limit, deny, redirect, başlık ekleme (set_header), mTLS zorunluluğu (require_mTLS), WAF (waf) ve webhook imza doğrulama (verify_webhook). WAF, OWASP-lite kurallarıyla SQL enjeksiyonu, XSS, path traversal, komut enjeksiyonu ve tarayıcı User-Agent'larını yakalar; ayrıca özel regex kuralı ekleyebilirsin. Yol, sorgu, User-Agent, Referer ve Cookie kontrol edilir (istek gövdesi kontrol edilmez); eşleşen istek 403 alır. verify_webhook GitHub, Stripe, GitLab, Shopify ve Slack imzalarını doğrular (5 dakika tolerans, gövde en çok 1 MB); geçersiz imza 401 ile reddedilir. Secret Vault Pro+ sırlarını şifreli saklar; {{secret:ad}} yalnızca verify_webhook'un secret_ref alanında çözülür.

İstek işleme sırası: ücretsiz planın ilk ziyaret ara sayfası politika motorundan önce, tünel başına istek sınırı ise politikalardan sonra çalışır. Yük dengeleme Team+: round robin, ağırlıklı (weighted), en az bağlantı (least connections) ve gecikme (latency) stratejileri; HTTP ve TCP sağlık kontrolleri.

Plan kapıları

Kota aşıldığında bağlantı kesilmez, hız düşürülür: Free 1, Hobby 5, Pro 10, Team 25, Enterprise 100 Mbps. Pro planında 7 günlük ücretsiz deneme vardır. Log saklama süresi plana göre uygulanır (Free 1, Hobby 3, Pro 7, Team 30, Enterprise 90 gün; saatlik temizlik işi); denetim kaydı (audit log) 365 gün tutulur. Team'de ek cihaz (0,50 $/cihaz/ay) ve ek trafik (0,10 $/GB) panelde Kotalar ve Planlar bölümünden talep edilir; onaylandığında limitlerin artar.

Ziyaretçi giriş sayfaları

HTTP tünelinde erişim politikası (Basic Auth ya da Google / GitHub) açıksa ziyaretçiler tarayıcının parola penceresi yerine Zorven temalı bir giriş sayfası görür. Sayfa Türkçe ve İngilizce, açık ve koyu temada ve mobilde çalışır.

• Kullanıcı adı ve parola: oturum 12 saat sürer. Parolayı değiştirirsen mevcut oturumlar geçersiz olur. Aynı IP için 10 dakikada en fazla 10 başarısız deneme yapılabilir. curl ve API istemcileri Authorization: Basic başlığıyla geçmeye devam eder.
• Google / GitHub ile devam et: yalnızca tünelin izin verdiği sağlayıcılar görünür; izinli e-posta listesi uygulanır ve ziyaretçi hesap değiştirebilir.
• İstatistik: her deneme (yöntem, sağlayıcı, kimlik, başarı, neden, IP, user agent) kaydedilir; parola kaydedilmez. Kayıtlar planın log saklama süresi kadar tutulur. GET /api/v1/tunnels/{id}/access-events listeyi, GET /api/v1/tunnels/{id}/access-events/summary?window=24h|7d|30d özeti verir (analytics:read kapsamı). Panel ekranı sonra gelecek.

Web ile kapı açma (TCP/UDP) Pro+

Ham TCP/UDP (SNI dahil) tüneller için ziyaretçi web üzerinden giriş yapar ve yalnızca kendi IP adresi tünelin portuna izinli olur. İzni olmayan bağlantılar sessizce düşer.

1. Tünele önce bir giriş yöntemi ver: kullanıcı adı ve parola ya da Google / GitHub (erişim politikası).
2. Kapıyı aç ve izin süresini seç: 3600 (1 saat), 43200 (12 saat), 86400 (24 saat) ya da 604800 (7 gün).
3. Kapı adresini ziyaretçiyle paylaş: door--<etiket>.zorven.app. Ziyaretçi giriş yapınca IP'si süre dolana kadar porta erişir; isterse kapıyı kendisi kapatabilir.

Engellenen denemeler erişim istatistiğinde sayılır. Plan Pro'nun altına düşerse kapı otomatik kapanır. IPv6 ile IPv4 arasında eşleştirme yapılmaz.

Posta uygulamalarında kullan

Platform posta kutunu (org-adi@mail.zorven.app) mail uygulamalarında IMAP ve SMTP ile kullanabilirsin. Panelde Mail bölümündeki "Mail uygulamalarında kullan" alanından kutu başına uygulama parolası oluştur; parola bir kez gösterilir ve istediğin an iptal edilir.

• Gmail uygulaması (Android / iOS): hesap ekle, "Diğer" ya da "Kişisel (IMAP)" seç, yukarıdaki ayarları gir.
• Outlook ve Thunderbird: otomatik yapılandırma (autoconfig / autodiscover) uç noktaları vardır; adresi girmen yeterli olabilir.
• Apple Mail: panelden yapılandırma profilini indirip kur.
• Harici alıcılara gönderim webmail ile aynı plan kuralına bağlıdır (Enterprise); platform içi adreslere her zaman teslim edilir.
• POP3 sunulmaz, yalnızca IMAP vardır. Gmail'in web sitesi harici hesabı POP3 ile eklediği için gmail.com'a eklenemez; Gmail uygulamasını kullan.

API ve token'lar

Panelde yapılan her şeyi REST API ile de yapabilirsin. API erişimi Pro+ planlarda açıktır. Panelde API Anahtarları bölümünden kapsam (scope) ve süre seçerek bir API token'ı oluştur ve her isteğe Authorization başlığıyla ekle:

İki token türünü karıştırma: zrv_live_ istemci (cihaz) token'ıdır ve zorven authtoken ile kullanılır; zrv_api_ API token'ıdır ve REST API ile zorven connect için geçerlidir. Tüm uçlar ve kapsamlar için API referansına bak.

Yardım

Sık sorulan sorular için SSS, sistem durumu için durum sayfası, diğer konular için iletişim sayfası. İstemci ve sunucu kodu açık çekirdektir (AGPLv3): GitHub.