Add initial README with usage examples and API documentation

2025-10-22 23:01:32 +05:00
parent a305b7f55a
commit 7360c05f9b
1 changed files with 88 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,88 @@
+# go-nftables-client
+
+Go-низкоуровневая обёртка для управления [nftables](https://wiki.nftables.org/wiki-nftables/index.php/Main_Page) через командную строку.
+
+## Возможности
+
+- Добавление и удаление таблиц (`add table`, `delete table`)
+- Добавление и удаление цепочек (`add chain`, `delete chain`, настройка hook/policy)
+- Добавление, удаление, очистка правил (`add rule`, `delete rule`, `flush`)
+- Абстракции для работы с IP/IP6/inet/arp/bridge/netdev families
+- Интерфейс для выполнения CLI-команд nftables напрямую
+- Простой и минималистичный API для быстрой интеграции
+
+## Установка
+```sh
+go get git.kor-elf.net/kor-elf-shield/go-nftables-client
+```
+
+## Пример использования
+
+```go
+package main
+
+import (
+    "log"
+    "git.kor-elf.net/kor-elf-shield/go-nftables-client"
+    "git.kor-elf.net/kor-elf-shield/go-nftables-client/family"
+	"git.kor-elf.net/kor-elf-shield/go-nftables-client/chain"
+)
+
+func main() {
+    nft, err := nft.New()
+    if err != nil {
+        log.Fatalf("nft not found: %v", err)
+    }
+
+    // Добавить таблицу
+    if err := nft.Table().Add(family.IP, "test"); err != nil {
+        log.Fatalf("table add failed: %v", err)
+    }
+
+    chainType := chain.NewBaseChainOptions(chain.TypeFilter)
+    chainType.Hook = chain.HookOutput
+    chainType.Priority = 0
+    chainType.Policy = chain.PolicyAccept
+    if err := nft.Chain().Add(family.IP, "test", "test", chainType); err != nil {
+        log.Fatalf("table add failed: %v", err)
+    }
+
+    // Добавить правило (пример: дропать пакеты от 1.2.3.4)
+    if err := nft.Rule().Add(family.IP, "test", "test", "ip", "saddr", "1.2.3.4", "drop"); err != nil {
+        log.Fatalf("rule add failed: %v", err)
+    }
+}
+```
+
+## Краткое описание API
+
+```go
+nft.Table().Add(family.Type, tableName string) error
+nft.Table().Delete(family.Type, tableName string) error
+nft.Table().Clear(family.Type, tableName string) error
+
+nft.Chain().Add(family.Type, table, chain string, baseChain chain.ChainOptions) error
+nft.Chain().Create(family family.Type, table, chain string, baseChain chain.ChainOptions) error
+nft.Chain().Rename(family family.Type, table, oldChainName, newChainName string) error
+nft.Chain().Delete(family.Type, table, chain string) error
+nft.Chain().Clear(family.Type, table, chain string) error
+
+nft.Rule().Add(family.Type, table, chain string, expr ...string) error
+nft.Rule().Insert(family family.Type, table, chain string, expr ...string) error
+nft.Rule().Replace(family family.Type, table, chain string, handle uint64, expr ...string) error
+nft.Rule().Delete(family family.Type, table, chain string, handle uint64) error
+
+
+nft.Clear() error           // flush ruleset
+nft.Version() (Version, error) // информация о версии nftables
+nft.Command() command.NFT   // ручное выполнение любых nft-команд
+```
+
+## Требования
+
+- Go 1.25+
+- Установленный nft (`/usr/sbin/nft`, `/sbin/nft` или доступен через PATH)
+
+## Лицензия
+
+[MIT](https://git.kor-elf.net/kor-elf-shield/go-nftables-client/src/branch/main/LICENSE)