From cf62af87db9f84f496669c03993468384340f8c6 Mon Sep 17 00:00:00 2001 From: Sarv Date: Sat, 4 Nov 2023 22:25:15 +0800 Subject: [PATCH] add document (#15) --- README.md | 19 ++- README_en.md | 35 +++- cmd/ips/cmd_config.go | 35 ++-- cmd/ips/cmd_download.go | 21 ++- cmd/ips/cmd_dump.go | 26 +-- cmd/ips/cmd_myip.go | 34 ++-- cmd/ips/cmd_pack.go | 27 +-- cmd/ips/cmd_root.go | 49 ++++-- cmd/ips/cmd_server.go | 24 +-- cmd/ips/const.go | 56 +++++++ docs/advanced_usage.md | 59 +++++++ docs/advanced_usage_en.md | 59 +++++++ docs/config.md | 334 +++++++++++++++++++++++++++++++++++++ docs/config_en.md | 335 ++++++++++++++++++++++++++++++++++++++ docs/download.md | 78 +++++++++ docs/download_en.md | 66 ++++++++ docs/dump.md | 74 +++++++++ docs/dump_en.md | 75 +++++++++ docs/format_ipdb.md | 94 +++++++++++ docs/format_ipdb_en.md | 94 +++++++++++ docs/myip.md | 0 docs/pack.md | 67 ++++++++ docs/pack_en.md | 68 ++++++++ docs/query.md | 93 +++++++++++ docs/query_en.md | 93 +++++++++++ docs/server.md | 110 +++++++++++++ docs/server_en.md | 95 +++++++++++ docs/usage.md | 22 +++ docs/usage_en.md | 22 +++ internal/ips/config.go | 2 +- 30 files changed, 2060 insertions(+), 106 deletions(-) create mode 100644 cmd/ips/const.go create mode 100644 docs/advanced_usage.md create mode 100644 docs/advanced_usage_en.md create mode 100644 docs/config.md create mode 100644 docs/config_en.md create mode 100644 docs/download.md create mode 100644 docs/download_en.md create mode 100644 docs/dump.md create mode 100644 docs/dump_en.md create mode 100644 docs/format_ipdb.md create mode 100644 docs/format_ipdb_en.md create mode 100644 docs/myip.md create mode 100644 docs/pack.md create mode 100644 docs/pack_en.md create mode 100644 docs/query.md create mode 100644 docs/query_en.md create mode 100644 docs/server.md create mode 100644 docs/server_en.md create mode 100644 docs/usage.md create mode 100644 docs/usage_en.md diff --git a/README.md b/README.md index fdd5dcf..43b3ecd 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,21 @@ ips 是一个命令行工具与库，可以轻松完成 IP 地理位置数据库 go install github.com/sjzar/ips@latest ``` +#### 二进制安装 + +[![Windows](https://img.shields.io/badge/-Windows_x64-blue.svg?style=for-the-badge&logo=windows)](https://github.com/sjzar/ips/releases/latest/download/ips_windows.exe) +[![Unix](https://img.shields.io/badge/-Linux/BSD-red.svg?style=for-the-badge&logo=linux)](https://github.com/sjzar/ips/releases/latest/download/ips_linux) +[![MacOS](https://img.shields.io/badge/-MacOS-lightblue.svg?style=for-the-badge&logo=apple)](https://github.com/sjzar/ips/releases/latest/download/ips_macos) + +从 [GitHub Releases](https://github.com/sjzar/ips/releases) 下载最新版本的二进制文件。 + +#### Homebrew 安装 + +```bash +brew tap sjzar/tap +brew install ips +``` + ### 特性 * 一键查询、转存和打包 IP 地理位置数据库 @@ -30,7 +45,7 @@ go install github.com/sjzar/ips@latest | 数据库 | 查询 | 转存 | 打包 | 官方网站 | 说明 | |:----------|:---|:---|:---|:--------------------------------------------------|:----------| -| txt | - | ✅ | ✅ | - | 本项目转存时使用 | +| txt | ✅ | ✅ | ✅ | - | 本项目转存时使用 | | ipdb | ✅ | ✅ | ✅ | [Link](https://ipip.net) | | | mmdb | ✅ | ✅ | ✅ | [Link](https://maxmind.com) | | | awdb | ✅ | ✅ | - | [Link](https://ipplus360.com) | | @@ -40,6 +55,8 @@ go install github.com/sjzar/ips@latest ### 使用方法 +更详细的使用说明请翻阅 [usage.md](./docs/usage.md) 。 + #### 查询 ```shell diff --git a/README_en.md b/README_en.md index e955455..a2f1a63 100644 --- a/README_en.md +++ b/README_en.md @@ -17,6 +17,21 @@ ips is a command-line tool and library that facilitates the querying, dumping, a go install github.com/sjzar/ips@latest ``` +#### Binary Installation + +[![Windows](https://img.shields.io/badge/-Windows_x64-blue.svg?style=for-the-badge&logo=windows)](https://github.com/sjzar/ips/releases/latest/download/ips_windows.exe) +[![Unix](https://img.shields.io/badge/-Linux/BSD-red.svg?style=for-the-badge&logo=linux)](https://github.com/sjzar/ips/releases/latest/download/ips_linux) +[![MacOS](https://img.shields.io/badge/-MacOS-lightblue.svg?style=for-the-badge&logo=apple)](https://github.com/sjzar/ips/releases/latest/download/ips_macos) + +Download the latest binary files from [GitHub Releases](https://github.com/sjzar/ips/releases). + +#### Homebrew Installation + +```shell +brew tap sjzar/tap +brew install ips +``` + ### Features * One-click querying, dumping, and packaging of IP geolocation databases @@ -28,18 +43,20 @@ go install github.com/sjzar/ips@latest ### Supported Databases -| Database | Query | Dump | Pack | Official Website | Command | -|:----------|:---|:---|:---|:--------------------------------------------------|:----------| -| txt | - | ✅ | ✅ | - | Used for project dumps | -| ipdb | ✅ | ✅ | ✅ | [Link](https://ipip.net) | | -| mmdb | ✅ | ✅ | ✅ | [Link](https://maxmind.com) | | -| awdb | ✅ | ✅ | - | [Link](https://ipplus360.com) | | -| qqwry | ✅ | ✅ | - | [Link](https://cz88.net) | IPv4 only | -| zxinc | ✅ | ✅ | - | [Link](https://ip.zxinc.org) | IPv6 only | -| ip2region | ✅ | ✅ | - | [Link](https://github.com/lionsoul2014/ip2region) | IPv4 only | +| Database | Query | Dump | Pack | Official Website | Command | +|:----------|:------|:-----|:-----|:--------------------------------------------------|:-----------------------| +| txt | ✅ | ✅ | ✅ | - | Used for project dumps | +| ipdb | ✅ | ✅ | ✅ | [Link](https://ipip.net) | | +| mmdb | ✅ | ✅ | ✅ | [Link](https://maxmind.com) | | +| awdb | ✅ | ✅ | - | [Link](https://ipplus360.com) | | +| qqwry | ✅ | ✅ | - | [Link](https://cz88.net) | IPv4 only | +| zxinc | ✅ | ✅ | - | [Link](https://ip.zxinc.org) | IPv6 only | +| ip2region | ✅ | ✅ | - | [Link](https://github.com/lionsoul2014/ip2region) | IPv4 only | ### Usage +For more detailed usage instructions, please refer to [usage_en.md](./docs/usage_en.md). + #### Query ```shell diff --git a/cmd/ips/cmd_config.go b/cmd/ips/cmd_config.go index 50da477..c3c085a 100644 --- a/cmd/ips/cmd_config.go +++ b/cmd/ips/cmd_config.go @@ -37,26 +37,31 @@ func init() { var configCmd = &cobra.Command{ Use: "config [set ] [unset ] [reset]", - Short: "View or modify ips configuration items", - Long: `Example: - # set ipv4 database file path - ips config set ipv4 ~/path/to/ipv4.db + Short: "Manage IPS configuration settings", + Long: `The 'ips config' command allows you to view and change various settings for IPS. - # set ipv4 database format - ips config set ipv4_format ipdb +You can specify database file paths, select output fields, and choose the format for IP databases. - # set query fields - ips config set fields "country,province,city,isp" +Use 'set' to change a setting, 'unset' to remove it, and 'reset' to revert all settings to default values. - # unset ipv6 database file path - ips config unset ipv6 +For IPv6, use similar commands, like 'ips config set ipv6_format mmdb' to specify the format. - # reset config - ips config reset +For more detailed information and advanced configuration options, please refer to https://github.com/sjzar/ips/blob/main/docs/config.md +`, + Example: ` # Set the IPv4 database file path: + ips config set ipv4 ~/path/to/ipv4.db - # ipv4 format: ipip, qqwry, maxmind, ip2region, dbip - # ipv6 format: zxinc, maxmind, dbip - # use 'ips config set ipv4 ipdb' or 'ips config set ipv6 zxinc' to set format`, + # Set the IPv4 database format: + ips config set ipv4_format ipdb + + # Configure the fields to display in query results: + ips config set fields "country,province,city,isp" + + # Remove the IPv6 database file path setting: + ips config unset ipv6 + + # Reset all configuration settings to their default values: + ips config reset`, PreRun: PreRunInit, Run: Config, } diff --git a/cmd/ips/cmd_download.go b/cmd/ips/cmd_download.go index 590fd93..f672006 100644 --- a/cmd/ips/cmd_download.go +++ b/cmd/ips/cmd_download.go @@ -31,17 +31,20 @@ func init() { } var downloadCmd = &cobra.Command{ - Use: "download [file] [url]", - Short: "Download database files", - Long: `Example: - # download list file city.free.ipdb - ips download city.free.ipdb + Use: "download [database_name] [custom_url]", + Short: "Download IP database files", + Long: `The 'ips download' command facilitates the acquisition and updating of IP geolocation database files. - # download another database file - ips download city.ipdb https://foo.com/city.ipdb +For more detailed information and advanced configuration options, please refer to https://github.com/sjzar/ips/blob/main/docs/download.md +`, + Example: ` # To download a predefined database file + ips download city.free.ipdb - # set database file after download - ips config set ipv4 city.ipdb`, + # To download a database file from a custom URL + ips download city.ipdb https://foo.com/city.ipdb + + # To configure the downloaded file as the default IPv4 database + ips config set ipv4 city.ipdb`, PreRun: PreRunInit, Run: Download, } diff --git a/cmd/ips/cmd_dump.go b/cmd/ips/cmd_dump.go index a19c383..3910c18 100644 --- a/cmd/ips/cmd_dump.go +++ b/cmd/ips/cmd_dump.go @@ -27,26 +27,30 @@ func init() { rootCmd.AddCommand(dumpCmd) // operate - dumpCmd.Flags().StringVarP(&dpFields, "fields", "f", "", "Specify the fields to be dumped from the input file. Default is all fields.") - dumpCmd.Flags().StringVarP(&dpRewriterFiles, "rewrite-files", "r", "", "List of files that need to be rewritten based on the given configurations.") - dumpCmd.Flags().StringVarP(&lang, "lang", "", "", "Set the language for the output. Example values: en, zh-CN, etc.") + dumpCmd.Flags().StringVarP(&dpFields, "fields", "f", "", UsageDPFields) + dumpCmd.Flags().StringVarP(&dpRewriterFiles, "rewrite-files", "r", "", UsageRewriteFiles) + dumpCmd.Flags().StringVarP(&lang, "lang", "", "", UsageLang) // input & output - dumpCmd.Flags().StringVarP(&inputFile, "input-file", "i", "", "Path to the IP database file.") - dumpCmd.Flags().StringVarP(&inputFormat, "input-format", "", "", "Specify the format of the input file. Examples: ipdb, mmdb, etc.") - dumpCmd.Flags().StringVarP(&readerOption, "input-option", "", "", "Specify the option for database reader.") - dumpCmd.Flags().StringVarP(&outputFile, "output-file", "o", "", "Path to the dumped file.") + dumpCmd.Flags().StringVarP(&inputFile, "input-file", "i", "", UsageDPInputFile) + dumpCmd.Flags().StringVarP(&inputFormat, "input-format", "", "", UsageDPInputFormat) + dumpCmd.Flags().StringVarP(&readerOption, "input-option", "", "", UsageReaderOption) + dumpCmd.Flags().StringVarP(&outputFile, "output-file", "o", "", UsageDumpOutputFile) } var dumpCmd = &cobra.Command{ Use: "dump -i inputFile [--input-format] [-o outputFile]", - Short: "Dump data from IP database file to plain file.", - Long: `Dump data from IP database file to plain file. + Short: "Export IP database contents to a text file", + Long: `Use the 'ips dump' command to extract and export data from IP databases into a plain text format, which can be tailored by specifying fields, formats, and languages. -Example: - ips dump -i geoip.mmdb -o geoip.txt +For more detailed information and advanced configuration options, please refer to https://github.com/sjzar/ips/blob/main/docs/dump.md `, + Example: ` # Export all fields from an IP database file to a text file + ips dump -i geoip.mmdb -o geoip.txt + + # Export specific fields (country and city) from an IP database file + ips dump -i geoip.mmdb -o geoip.txt --fields "country,city"`, PreRun: PreRunInit, Run: Dump, } diff --git a/cmd/ips/cmd_myip.go b/cmd/ips/cmd_myip.go index 8048093..2e17a4d 100644 --- a/cmd/ips/cmd_myip.go +++ b/cmd/ips/cmd_myip.go @@ -31,32 +31,32 @@ func init() { myipCmd.Flags().IntVarP(&myIPTimeoutS, "timeout", "", 0, "Set the maximum wait time for detectors.") // operate - myipCmd.Flags().StringVarP(&fields, "fields", "f", "", "Specify the fields of interest for the IP data. Separate multiple fields with commas.") - myipCmd.Flags().BoolVarP(&useDBFields, "use-db-fields", "", false, "Use field names as they appear in the database. Default is common field names.") - myipCmd.Flags().StringVarP(&rewriteFiles, "rewrite-files", "r", "", "List of files that need to be rewritten based on the given configurations.") - myipCmd.Flags().StringVarP(&lang, "lang", "", "", "Set the language for the output. Example values: en, zh-CN, etc.") + myipCmd.Flags().StringVarP(&fields, "fields", "f", "", UsageFields) + myipCmd.Flags().BoolVarP(&useDBFields, "use-db-fields", "", false, UsageUseDBFields) + myipCmd.Flags().StringVarP(&rewriteFiles, "rewrite-files", "r", "", UsageRewriteFiles) + myipCmd.Flags().StringVarP(&lang, "lang", "", "", UsageLang) // database - myipCmd.Flags().StringVarP(&rootFile, "file", "i", "", "Path to the IPv4 and IPv6 database file.") - myipCmd.Flags().StringVarP(&rootFormat, "format", "", "", "Specify the format of the database. Examples: ipdb, mmdb, etc.") - myipCmd.Flags().StringVarP(&rootIPv4File, "ipv4-file", "", "", "Path to the IPv4 database file.") - myipCmd.Flags().StringVarP(&rootIPv4Format, "ipv4-format", "", "", "Specify the format for IPv4 data. Examples: ipdb, mmdb, etc.") - myipCmd.Flags().StringVarP(&rootIPv6File, "ipv6-file", "", "", "Path to the IPv6 database file.") - myipCmd.Flags().StringVarP(&rootIPv6Format, "ipv6-format", "", "", "Specify the format for IPv6 data. Examples: ipdb, mmdb, etc.") - myipCmd.Flags().StringVarP(&readerOption, "database-option", "", "", "Specify the option for database reader.") + myipCmd.Flags().StringVarP(&rootFile, "file", "i", "", UsageQueryFile) + myipCmd.Flags().StringVarP(&rootFormat, "format", "", "", UsageQueryFormat) + myipCmd.Flags().StringVarP(&rootIPv4File, "ipv4-file", "", "", UsageQueryIPv4File) + myipCmd.Flags().StringVarP(&rootIPv4Format, "ipv4-format", "", "", UsageQueryIPv4Format) + myipCmd.Flags().StringVarP(&rootIPv6File, "ipv6-file", "", "", UsageQueryIPv6File) + myipCmd.Flags().StringVarP(&rootIPv6Format, "ipv6-format", "", "", UsageQueryIPv6Format) + myipCmd.Flags().StringVarP(&readerOption, "database-option", "", "", UsageReaderOption) // output - myipCmd.Flags().StringVarP(&rootTextFormat, "text-format", "", "", "Specify the desired format for text output. It supports %origin and %values parameters.") - myipCmd.Flags().StringVarP(&rootTextValuesSep, "text-values-sep", "", "", "Specify the separator for values in text output. (default is space)") - myipCmd.Flags().BoolVarP(&rootJson, "json", "j", false, "Output the results in JSON format.") - myipCmd.Flags().BoolVarP(&rootJsonIndent, "json-indent", "", false, "Output the results in indent JSON format.") - myipCmd.Flags().BoolVarP(&rootAlfred, "alfred", "", false, "Output the results in Alfred format.") + myipCmd.Flags().StringVarP(&rootTextFormat, "text-format", "", "", UsageTextFormat) + myipCmd.Flags().StringVarP(&rootTextValuesSep, "text-values-sep", "", "", UsageTextValuesSep) + myipCmd.Flags().BoolVarP(&rootJson, "json", "j", false, UsageJson) + myipCmd.Flags().BoolVarP(&rootJsonIndent, "json-indent", "", false, UsageJsonIndent) + myipCmd.Flags().BoolVarP(&rootAlfred, "alfred", "", false, UsageAlfred) } var myipCmd = &cobra.Command{ Use: "myip", - Short: "Retrieve your public IP address.", + Short: "Retrieve your public IP address", Long: `The 'myip' command uses multiple detectors to discover and return your public IP address. It is designed to work in scenarios with multiple network interfaces and allows you to specify the local address for outbound connections, the number of detectors to confirm the IP, and the timeout diff --git a/cmd/ips/cmd_pack.go b/cmd/ips/cmd_pack.go index 335051d..5a8dce1 100644 --- a/cmd/ips/cmd_pack.go +++ b/cmd/ips/cmd_pack.go @@ -25,28 +25,29 @@ func init() { rootCmd.AddCommand(packCmd) // operate - packCmd.Flags().StringVarP(&dpFields, "fields", "f", "", "Specify the fields to be dumped from the input file. Default is all fields.") - packCmd.Flags().StringVarP(&dpRewriterFiles, "rewrite-files", "r", "", "List of files that need to be rewritten based on the given configurations.") - packCmd.Flags().StringVarP(&lang, "lang", "", "", "Set the language for the output. Example values: en, zh-CN, etc.") + packCmd.Flags().StringVarP(&dpFields, "fields", "f", "", UsageDPFields) + packCmd.Flags().StringVarP(&dpRewriterFiles, "rewrite-files", "r", "", UsageRewriteFiles) + packCmd.Flags().StringVarP(&lang, "lang", "", "", UsageLang) // input & output - packCmd.Flags().StringVarP(&inputFile, "input-file", "i", "", "Path to the IP database file.") - packCmd.Flags().StringVarP(&inputFormat, "input-format", "", "", "Specify the format of the input file. Examples: ipdb, mmdb, etc.") - packCmd.Flags().StringVarP(&readerOption, "input-option", "", "", "Specify the option for database reader.") - packCmd.Flags().StringVarP(&outputFile, "output-file", "o", "", "Path to the packed IP database file.") - packCmd.Flags().StringVarP(&outputFormat, "output-format", "", "", "Specify the format of the output file. Examples: ipdb, mmdb, etc.") - packCmd.Flags().StringVarP(&writerOption, "output-option", "", "", "Specify the option for database writer.") + packCmd.Flags().StringVarP(&inputFile, "input-file", "i", "", UsageDPInputFile) + packCmd.Flags().StringVarP(&inputFormat, "input-format", "", "", UsageDPInputFormat) + packCmd.Flags().StringVarP(&readerOption, "input-option", "", "", UsageReaderOption) + packCmd.Flags().StringVarP(&outputFile, "output-file", "o", "", UsagePackOutputFile) + packCmd.Flags().StringVarP(&outputFormat, "output-format", "", "", UsagePackOutputFormat) + packCmd.Flags().StringVarP(&writerOption, "output-option", "", "", UsageWriterOption) } var packCmd = &cobra.Command{ Use: "pack -i inputFile [--input-format format] -o outputFile [--output-format format]", - Short: "Pack data from IP database file to another IP database file.", - Long: `Pack data from IP database file to another IP database file. + Short: "Repackage IP database file", + Long: `The 'ips pack' command enables users to create a new IP database file from an existing one while allowing for customization of the data fields included. -Example: - ips pack -i geoip.mmdb -o geoip.ipdb +For more detailed information and advanced configuration options, please refer to https://github.com/sjzar/ips/blob/main/docs/pack.md `, + Example: ` # Package IP Database and Specify Fields + ips pack -i geoip.mmdb -o geoip_custom.ipdb --fields "country,city"`, PreRun: PreRunInit, Run: Pack, } diff --git a/cmd/ips/cmd_root.go b/cmd/ips/cmd_root.go index 75e61b2..78f2b6e 100644 --- a/cmd/ips/cmd_root.go +++ b/cmd/ips/cmd_root.go @@ -35,29 +35,30 @@ var manager *ips.Manager // Initialization function for setting up command line arguments and flags. func init() { // common - rootCmd.PersistentFlags().StringVarP(&logLevel, "loglevel", "", "info", "Set the desired verbosity level for logging. Example values: debug, info, warn, etc.") + rootCmd.PersistentFlags().StringVarP(&logLevel, "loglevel", "", "info", UsageLogLevel) // operate - rootCmd.Flags().StringVarP(&fields, "fields", "f", "", "Specify the fields of interest for the IP data. Separate multiple fields with commas.") - rootCmd.Flags().BoolVarP(&useDBFields, "use-db-fields", "", false, "Use field names as they appear in the database. Default is common field names.") - rootCmd.Flags().StringVarP(&rewriteFiles, "rewrite-files", "r", "", "List of files that need to be rewritten based on the given configurations.") - rootCmd.Flags().StringVarP(&lang, "lang", "", "", "Set the language for the output. Example values: en, zh-CN, etc.") + + rootCmd.Flags().StringVarP(&fields, "fields", "f", "", UsageFields) + rootCmd.Flags().BoolVarP(&useDBFields, "use-db-fields", "", false, UsageUseDBFields) + rootCmd.Flags().StringVarP(&rewriteFiles, "rewrite-files", "r", "", UsageRewriteFiles) + rootCmd.Flags().StringVarP(&lang, "lang", "", "", UsageLang) // database - rootCmd.Flags().StringVarP(&rootFile, "file", "i", "", "Path to the IPv4 and IPv6 database file.") - rootCmd.Flags().StringVarP(&rootFormat, "format", "", "", "Specify the format of the database. Examples: ipdb, mmdb, etc.") - rootCmd.Flags().StringVarP(&rootIPv4File, "ipv4-file", "", "", "Path to the IPv4 database file.") - rootCmd.Flags().StringVarP(&rootIPv4Format, "ipv4-format", "", "", "Specify the format for IPv4 data. Examples: ipdb, mmdb, etc.") - rootCmd.Flags().StringVarP(&rootIPv6File, "ipv6-file", "", "", "Path to the IPv6 database file.") - rootCmd.Flags().StringVarP(&rootIPv6Format, "ipv6-format", "", "", "Specify the format for IPv6 data. Examples: ipdb, mmdb, etc.") - rootCmd.Flags().StringVarP(&readerOption, "database-option", "", "", "Specify the option for database reader.") + rootCmd.Flags().StringVarP(&rootFile, "file", "i", "", UsageQueryFile) + rootCmd.Flags().StringVarP(&rootFormat, "format", "", "", UsageQueryFormat) + rootCmd.Flags().StringVarP(&rootIPv4File, "ipv4-file", "", "", UsageQueryIPv4File) + rootCmd.Flags().StringVarP(&rootIPv4Format, "ipv4-format", "", "", UsageQueryIPv4Format) + rootCmd.Flags().StringVarP(&rootIPv6File, "ipv6-file", "", "", UsageQueryIPv6File) + rootCmd.Flags().StringVarP(&rootIPv6Format, "ipv6-format", "", "", UsageQueryIPv6Format) + rootCmd.Flags().StringVarP(&readerOption, "database-option", "", "", UsageReaderOption) // output - rootCmd.Flags().StringVarP(&rootTextFormat, "text-format", "", "", "Specify the desired format for text output. It supports %origin and %values parameters.") - rootCmd.Flags().StringVarP(&rootTextValuesSep, "text-values-sep", "", "", "Specify the separator for values in text output. (default is space)") - rootCmd.Flags().BoolVarP(&rootJson, "json", "j", false, "Output the results in JSON format.") - rootCmd.Flags().BoolVarP(&rootJsonIndent, "json-indent", "", false, "Output the results in indent JSON format.") - rootCmd.Flags().BoolVarP(&rootAlfred, "alfred", "", false, "Output the results in Alfred format.") + rootCmd.Flags().StringVarP(&rootTextFormat, "text-format", "", "", UsageTextFormat) + rootCmd.Flags().StringVarP(&rootTextValuesSep, "text-values-sep", "", "", UsageTextValuesSep) + rootCmd.Flags().BoolVarP(&rootJson, "json", "j", false, UsageJson) + rootCmd.Flags().BoolVarP(&rootJsonIndent, "json-indent", "", false, UsageJsonIndent) + rootCmd.Flags().BoolVarP(&rootAlfred, "alfred", "", false, UsageAlfred) } var rootCmd = &cobra.Command{ @@ -65,8 +66,20 @@ var rootCmd = &cobra.Command{ Short: "IP Geolocation Database Tools", Long: `IP Geolocation Database Tools -ips is a command line tool for querying IP geolocation information and repacking database file. +The 'ips' is a command line tool for querying IP geolocation information and repacking database file. + +It allows for flexible queries via command-line or pipe input, supporting both IPv4 and IPv6 formats, and provides customizable outputs. + +For more detailed information and advanced configuration options, please refer to https://github.com/sjzar/ips/blob/main/docs/query.md `, + Example: ` # Standard IP query + ips 8.8.8.8 + + # Custom fields and output format + ips 8.8.8.8 -f "country,city" --text-format "%values" --text-values-sep ":" + + # Pipeline query + echo 8.8.8.8 | ips`, Args: cobra.MinimumNArgs(0), CompletionOptions: cobra.CompletionOptions{ HiddenDefaultCmd: true, diff --git a/cmd/ips/cmd_server.go b/cmd/ips/cmd_server.go index 7f2c804..f984f18 100644 --- a/cmd/ips/cmd_server.go +++ b/cmd/ips/cmd_server.go @@ -23,22 +23,22 @@ import ( func init() { rootCmd.AddCommand(serverCmd) // server - serverCmd.Flags().StringVarP(&addr, "addr", "a", "", "server listen address") + serverCmd.Flags().StringVarP(&addr, "addr", "a", "", "Listen address") // operate - serverCmd.Flags().StringVarP(&fields, "fields", "f", "", "Specify the fields of interest for the IP data. Separate multiple fields with commas.") - serverCmd.Flags().BoolVarP(&useDBFields, "use-db-fields", "", false, "Use field names as they appear in the database. Default is common field names.") - serverCmd.Flags().StringVarP(&rewriteFiles, "rewrite-files", "r", "", "List of files that need to be rewritten based on the given configurations.") - serverCmd.Flags().StringVarP(&lang, "lang", "", "", "Set the language for the output. Example values: en, zh-CN, etc.") + serverCmd.Flags().StringVarP(&fields, "fields", "f", "", UsageFields) + serverCmd.Flags().BoolVarP(&useDBFields, "use-db-fields", "", false, UsageUseDBFields) + serverCmd.Flags().StringVarP(&rewriteFiles, "rewrite-files", "r", "", UsageRewriteFiles) + serverCmd.Flags().StringVarP(&lang, "lang", "", "", UsageLang) // database - serverCmd.Flags().StringVarP(&rootFile, "file", "i", "", "Path to the IPv4 and IPv6 database file.") - serverCmd.Flags().StringVarP(&rootFormat, "format", "", "", "Specify the format of the database. Examples: ipdb, mmdb, etc.") - serverCmd.Flags().StringVarP(&rootIPv4File, "ipv4-file", "", "", "Path to the IPv4 database file.") - serverCmd.Flags().StringVarP(&rootIPv4Format, "ipv4-format", "", "", "Specify the format for IPv4 data. Examples: ipdb, mmdb, etc.") - serverCmd.Flags().StringVarP(&rootIPv6File, "ipv6-file", "", "", "Path to the IPv6 database file.") - serverCmd.Flags().StringVarP(&rootIPv6Format, "ipv6-format", "", "", "Specify the format for IPv6 data. Examples: ipdb, mmdb, etc.") - serverCmd.Flags().StringVarP(&readerOption, "database-option", "", "", "Specify the option for database reader.") + serverCmd.Flags().StringVarP(&rootFile, "file", "i", "", UsageQueryFile) + serverCmd.Flags().StringVarP(&rootFormat, "format", "", "", UsageQueryFormat) + serverCmd.Flags().StringVarP(&rootIPv4File, "ipv4-file", "", "", UsageQueryIPv4File) + serverCmd.Flags().StringVarP(&rootIPv4Format, "ipv4-format", "", "", UsageQueryIPv4Format) + serverCmd.Flags().StringVarP(&rootIPv6File, "ipv6-file", "", "", UsageQueryIPv6File) + serverCmd.Flags().StringVarP(&rootIPv6Format, "ipv6-format", "", "", UsageQueryIPv6Format) + serverCmd.Flags().StringVarP(&readerOption, "database-option", "", "", UsageReaderOption) } var serverCmd = &cobra.Command{ diff --git a/cmd/ips/const.go b/cmd/ips/const.go new file mode 100644 index 0000000..9f81b72 --- /dev/null +++ b/cmd/ips/const.go @@ -0,0 +1,56 @@ +/* + * Copyright (c) 2023 shenjunzheng@gmail.com + * + * Licensed under the Apache License, Version 2.0 (the "License"); + * you may not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, software + * distributed under the License is distributed on an "AS IS" BASIS, + * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. + * See the License for the specific language governing permissions and + * limitations under the License. + */ + +package ips + +const ( + // Flag Usage + // Global Flags + + UsageLogLevel = "Set the desired verbosity level for logging." + + // Operate Flags + + UsageLang = "Language for output data. (default \"zh-CN\")" + UsageFields = "Fields to include in the output, separated by commas. (default \"country,province,city,isp\")" + UsageUseDBFields = "Use field names as they appear in the database. Default is common field names." + UsageRewriteFiles = "Paths to files containing data rewrite rules, separated by commas." + UsageDPFields = "Fields to extract from the database. Defaults to all available fields." + + // Database Flags + + UsageQueryFile = "Path to the combined IPv4/IPv6 database file." + UsageQueryFormat = "The format of the IPv4/IPv6 database file." + UsageQueryIPv4File = "Path to the IPv4 database file." + UsageQueryIPv4Format = "The format of the IPv4 database file." + UsageQueryIPv6File = "Path to the IPv6 database file." + UsageQueryIPv6Format = "The format of the IPv6 database file." + UsageDPInputFile = "Path to the input IP database file (required)." + UsageDPInputFormat = "The format of the input IP database file." + UsageDumpOutputFile = "Destination path for the dumped data. Defaults to standard output if not specified." + UsagePackOutputFile = "Path to the output IP database file (required)." + UsagePackOutputFormat = "The format for the output IP database file." + UsageReaderOption = "Additional options for the database reader, if applicable." + UsageWriterOption = "Additional options for the database writer, if applicable." + + // Output Flags + + UsageTextFormat = "Specify the desired format for text output. (default \"%origin [%values]\")" + UsageTextValuesSep = "Specify the separator for values in text output. (default \" \")" + UsageJson = "Output the results in JSON format." + UsageJsonIndent = "Output the results in indent JSON format." + UsageAlfred = "Output the results in Alfred format." +) diff --git a/docs/advanced_usage.md b/docs/advanced_usage.md new file mode 100644 index 0000000..76ab16e --- /dev/null +++ b/docs/advanced_usage.md @@ -0,0 +1,59 @@ +# IPS 高级用法示例 + + +* [IPS 高级用法示例](#ips-高级用法示例) + * [减少字段以压缩数据库体积](#减少字段以压缩数据库体积) + * [制作自定义数据库](#制作自定义数据库) + + +## 减少字段以压缩数据库体积 + +商业数据库通常包含大量详细信息，如经纬度、时区和邮编等，其中高精度的经纬度信息尤其会占用较多空间。 + +然而，用户在实际应用中并不总是需要所有数据。根据业务需求裁剪不必要的字段可以有效减小数据库体积。 + +例如，[埃文科技](https://www.ipplus360.com)的商用 IPv4 数据库文件大小超过 600MB，这在分发和使用时带来了不便。 + +如果您在使用中，仅需要国家、省份和城市信息，可以使用以下命令来重打包数据库： + +```shell +# 将 ipv4.awdb 重打包为 ipv4_new.awdb，仅包含国家、省份、城市和运营商字段 +ips pack -i ./ipv4.awdb -f country,province,city,isp -o ./ipv4_new.ipdb +``` + +这样重新打包后的数据库文件大约为 120MB；我们仍然可以进一步减少数据量，例如，如果在中国地区需要细化到城市和运营商级别的数据，而海外地区仅需国家级别信息，可以使用以下命令来重打包： + +```shell +# 中国地区包含国家、省份、城市和运营商信息，海外地区仅包含国家信息 +ips pack -i ./ipv4.awdb -f 'country,province,city,isp|country=!中国:country' -o ./ipv4_new.ipdb +``` + +使用此命令重新打包后的数据库体积降至约 7.7MB，相较原文件缩减了大约 98% 的体积。这显著优化了数据库文件的分发效率，并降低了运行时的内存占用。 + +## 制作自定义数据库 + +IPS 允许用户转储数据库文件至文本格式，便于进行自定义修改。随后，用户可将修改后的文本文件重新打包成新的数据库文件，从而创建自定义数据库。 + +例如，若需判断某个 IP 是否属于自己公司，可以将公司的 IP 段以约定的格式写入文本文件，然后将其打包成数据库文件，实现自定义查询数据库。 + +由于 IP 数据库文件查询通常采用前缀树搜索算法，自定义数据库查询效率通常高于文本文件查询，并且分发起来更为便捷。 + +```shell +# 转存数据库为文本文件 +ips dump -i ./ipv4.awdb -o ./ipv4.txt + +# 将自定义文本文件打包成数据库文件 +ips pack -i ./custom.txt -o ./custom.ipdb +``` + +一些流量分流工具会使用 `mmdb` 格式的数据库文件来进行流量分流，IPS 也支持生成 `mmdb` 格式的数据库文件。 + +如果您的分流工具仅需 `geoname_id` 来获取国家信息，您甚至可以使用 `--output-option` 参数来移除 `mmdb` 文件中的多语言翻译数据，以进一步压缩文件大小。 + +```shell +# 将自定义文本文件打包成 mmdb 格式的数据库文件 +ips pack -i ./custom.txt -o ./custom.mmdb + +# 移除 mmdb 数据库文件中的多语言翻译数据 +ips pack -i ./custom.txt -o ./custom.mmdb --output-option "select_languages=-" +``` diff --git a/docs/advanced_usage_en.md b/docs/advanced_usage_en.md new file mode 100644 index 0000000..75d7c8b --- /dev/null +++ b/docs/advanced_usage_en.md @@ -0,0 +1,59 @@ +# IPS Advanced Usage Examples + + +* [IPS Advanced Usage Examples](#ips-advanced-usage-examples) + * [Reducing Fields to Compress Database Size](#reducing-fields-to-compress-database-size) + * [Creating Custom Databases](#creating-custom-databases) + + +## Reducing Fields to Compress Database Size + +Commercial databases typically contain a wealth of detailed information such as latitude and longitude, time zones, and postal codes, with high-precision latitude and longitude data particularly taking up a significant amount of space. + +However, users do not always require all this data in practice. Trimming unnecessary fields according to business needs can effectively reduce the database size. + +For example, the commercial IPv4 database file from [埃文科技](https://www.ipplus360.com) is over 600MB, which is inconvenient for distribution and use. + +If you only need country, province, and city information for your use, the following command can be used to repack the database: + +```shell +# Repack ipv4.awdb to ipv4_new.awdb, including only country, province, city, and ISP fields +ips pack -i ./ipv4.awdb -f country,province,city,isp -o ./ipv4_new.ipdb +``` + +The database file size after repacking is about 120MB; further data volume reduction is possible, for example, if city and ISP granularity data is needed in China, but only country-level data is needed overseas, the following command can repack the database accordingly: + +```shell +# Include country, province, city, and ISP information for China, and only country information for overseas +ips pack -i ./ipv4.awdb -f 'country,province,city,isp|country=!中国:country' -o ./ipv4_new.ipdb +``` + +The database size is reduced to approximately 7.7MB after repacking with this command, which is about a 98% reduction from the original file size. This significantly optimizes the efficiency of database distribution and reduces memory usage during operation. + +## Creating Custom Databases + +IPS allows users to dump database files into a text format, facilitating custom modifications. Subsequently, users can repack the modified text file into a new database file to create a custom database. + +For example, to determine if an IP belongs to your company, you can write your company's IP range into a text file in the specified format and then pack it into a database file for custom query purposes. + +Since IP database file queries typically use a prefix tree search algorithm, custom database queries usually offer higher efficiency than text file queries and are more convenient to distribute. + +```shell +# Dump the database into a text file +ips dump -i ./ipv4.awdb -o ./ipv4.txt + +# Pack the custom text file into a database file +ips pack -i ./custom.txt -o ./custom.ipdb +``` + +Some traffic shaping tools use `mmdb` format database files for routing, and IPS also supports generating `mmdb` format database files. + +If your traffic shaping tool only requires `geoname_id` to obtain country information, you can even use the `--output-option` parameter to remove multilingual translation data from the `mmdb` file to further reduce the file size. + +```shell +# Pack the custom text file into an mmdb format database file +ips pack -i ./custom.txt -o ./custom.mmdb + +# Remove multilingual translation data from the mmdb database file +ips pack -i ./custom.txt -o ./custom.mmdb --output-option "select_languages=-" +``` \ No newline at end of file diff --git a/docs/config.md b/docs/config.md new file mode 100644 index 0000000..5859317 --- /dev/null +++ b/docs/config.md @@ -0,0 +1,334 @@ +# IPS 配置说明 + + +* [IPS 配置说明](#ips-配置说明) + * [简介](#简介) + * [配置类型](#配置类型) + * [工作目录](#工作目录) + * [配置加载逻辑](#配置加载逻辑) + * [配置命令](#配置命令) + * [查看当前配置](#查看当前配置) + * [修改配置参数](#修改配置参数) + * [移除配置参数](#移除配置参数) + * [重置配置参数](#重置配置参数) + * [配置参数](#配置参数) + * [lang](#lang) + * [ipv4_file](#ipv4file) + * [ipv4_format](#ipv4format) + * [ipv6_file](#ipv6file) + * [ipv6_format](#ipv6format) + * [fields](#fields) + * [use_db_fields](#usedbfields) + * [rewrite_files](#rewritefiles) + * [output_type](#outputtype) + * [text_format](#textformat) + * [text_values_sep](#textvaluessep) + * [json_indent](#jsonindent) + * [dp_fields](#dpfields) + * [dp_rewriter_files](#dprewriterfiles) + * [reader_option](#readeroption) + * [writer_option](#writeroption) + * [myip_count](#myipcount) + * [myip_timeout_s](#myiptimeouts) + * [addr](#addr) + + +## 简介 + +IPS 为了满足不同用户的个性化需求，简化IP地理位置数据库的查询、转存和打包过程，提供了一套灵活的配置系统。 + +通过这套系统，用户可以定制IPS的行为，包括但不限于指定 IP 数据库、输出格式、查询字段等。 + +配置参数影响着 IPS 的使用效率和结果输出。合理的配置可以提升查询速度，优化输出内容，并且使得转存与打包操作更加符合用户的实际需求。 + +## 配置类型 + +IPS 的配置主要分为两大类： + +- **命令行参数**：直接在命令行中指定，适用于一次性任务或覆盖默认配置。 +- **配置文件**：在 IPS 工作目录下的 `ips.json` 文件中持久化保存，适用于常规操作和个性化设置。 + +## 工作目录 + +IPS 默认将用户的 HOME 目录下的 `.ips` 文件夹作为工作目录，路径为 `${HOME}/.ips`。 该目录负责存储配置文件和 IPS 下载的 IP 数据库文件。 + +如果 HOME 目录不可用，IPS 将使用系统的临时文件夹 `${TEMP}/.ips` 作为后备。 + +用户可以通过环境变量 `IPS_DIR` 来指定一个自定义的工作目录路径。 + +## 配置加载逻辑 + +IPS 在启动时会自动加载工作目录中的配置文件。如果配置文件不存在或部分参数缺失，IPS将采用内置的默认配置，并创建或更新配置文件。 + +需要注意的是，命令行参数会优先于配置文件中的设置，为用户提供更灵活的配置方式。 + +## 配置命令 + +IPS 通过 `ips config` 命令提供了查看和修改配置参数的能力。希望为用户提供一种比直接编辑配置文件更安全、更便捷的方式来管理IPS的配置。 + +### 查看当前配置 + +运行 `ips config` 不带任何额外参数将输出当前工具的配置参数。这是检查当前设置的快速方法，也可以用来确认之前的修改是否已经生效。 + +```shell +# 输出当前的配置参数 +$ ips config +IPS CONFIG ==================================================================== + +ips dir: [/Users/sarv/.ips] +ipv4_file(ipv4): [ipv4.awdb] +ipv6_file(ipv6): [GeoLite2-City.mmdb] +fields: [country,province,city,isp] +text_format: [%origin [%values] ] +text_values_sep: [ ] + +=============================================================================== +... <省略部分输出> ... +``` + +### 修改配置参数 + +使用 `ips config set` 子命令可以修改单个配置参数。修改成功后，IPS将显示一个确认信息。 + +```shell +# 将IPv4数据库文件路径设置为指定的文件 +$ ips config set ipv4 ~/path/to/ipv4.db +INFO[2023-11-02T13:08:01+08:00] set ipv4_file: [/Users/sarv/path/to/ipv4.db] success + +# 确认参数修改成功 +$ ips config +IPS CONFIG ==================================================================== + +ips dir: [/Users/sarv/.ips] +ipv4_file(ipv4): [/Users/sarv/path/to/ipv4.db] # 修改成功 +ipv6_file(ipv6): [GeoLite2-City.mmdb] +... <省略部分输出> ... +``` + +### 移除配置参数 + +使用 `ips config unset` 允许用户移除一个配置参数，将其值置空。请注意，这并不会恢复到默认值，而是在后续操作中需要显式指定或让IPS使用默认设置。 + +```shell +# 将IPv4数据库文件路径的配置移除 +$ ips config unset ipv4 +INFO[2023-11-02T13:09:15+08:00] unset ipv4_file success +``` + +### 重置配置参数 + +如果需要将所有的配置参数恢复到默认值，可以使用 `ips config reset` 子命令。这将丢弃所有用户自定义的配置，将IPS恢复到初始状态。 + +```shell +# 重置所有配置参数到默认值 +$ ips config reset +INFO[2023-11-02T13:12:21+08:00] reset config success +``` + +## 配置参数 + +IPS 提供了丰富的配置参数以适应不同的使用场景。以下是所有可用配置参数的详细介绍，包括它们的功能与默认值等信息。 + +### lang + +设置输出信息的语言，字符串参数。默认为 `zh-CN` (中文)，支持的语言列表如下： + +| 序号 | 语言 | 代码 | +|----|:-----|:--------| +| 1 | 英语 | `en` | +| 2 | 中文 | `zh-CN` | +| 3 | 俄语 | `ru` | +| 4 | 日语 | `ja` | +| 5 | 德语 | `de` | +| 6 | 法语 | `fr` | +| 7 | 西班牙语 | `es` | +| 8 | 葡萄牙语 | `pt-BR` | +| 9 | 波斯语 | `fa` | +| 10 | 韩语 | `ko` | + +需要注意的是，翻译数据源自 [GeoNames.org](https://geonames.org)。对于支持多语言的 IP 数据库，比如 `mmdb`，将直接使用数据库中的翻译数据。 + +### ipv4_file + +指定 IPv4 地址查询时使用的数据库文件，字符串参数，默认值为 `qqwry.dat`。 + +### ipv4_format + +指定 IPv4 数据库文件的格式，字符串参数。 + +当数据库文件后缀不足以确定文件格式时，用来指定 IPv4 数据库的格式。通常不需要设置。 + +### ipv6_file + +指定 IPv6 地址查询时使用的数据库文件，字符串参数，默认值为 `zxipv6wry.db`。 + +### ipv6_format + +指定 IPv6 数据库文件的格式，字符串参数。 + +当数据库文件后缀不足以确定文件格式时，用来指定 IPv6 数据库的格式。通常不需要设置。 + +### fields + +定义查询结果中显示哪些字段，字符串参数。默认值是 `country,province,city,isp`。该参数支持多种高级用法： + +**通用字段映射** + +除了直接使用数据库字段，`fields` 允许您使用通用字段，这意味着您可以使用一个字段名来引用不同数据库中可能有不同名称的相同类型数据。 + +例如通用字段 `country` 表示国家信息，可能在不同的数据库中表示为 `country`、`country_name`、`countryName` 等。 + +当前的通用字段有： + +| 序号 | 字段 | 说明 | +|----|:-------|:-------| +| 1 | `country` | 国家 | +| 2 | `province` | 省份 | +| 3 | `city` | 城市 | +| 4 | `isp` | 运营商 | +| 5 | `asn` | 自治域号 | +| 6 | `continent` | 大洲 | +| 7 | `utcOffset` | UTC 偏移值 | +| 8 | `latitude` | 纬度 | +| 9 | `longitude` | 经度 | +| 10 | `chinaAdminCode` | 中国行政区划代码 | + +数据库字段指的是不同数据库中特有的字段，例如 `mmdb` 中的 `subdivisions` 字段，`ip2region` 中的 `region` 字段等。 + +**条件字段选择** + +`fields` 还支持基于条件的字段选择。这允许您根据查询结果中的特定字段值来改变输出字段。 + +条件使用 URL 查询字符串格式，支持基本的逻辑运算，如 `country=中国`、`country=!中国`（非中国）、`country=中国/美国`（中国或美国）。 + +如果没有条件匹配，可以指定一个默认字段列表。这通过在条件选择语句的最后添加一个没有条件的字段列表来实现。 + +```shell +[|:|:|] + @ - 输出字段列表 + @ - 匹配条件 + @ - 默认字段列表 + +举例： + # 当查询的 IP 地址位于中国时，输出 country,province,city,isp 字段 + # 对于非中国的 IP 地址，只输出 country 字段 + "country,province,city,isp|country=!中国:country" +``` + +**魔法变量** + +`fields` 支持使用特定的魔法变量快速选择一组字段。当前支持的魔法变量有： + +| 序号 | 魔法变量 | 实际表示字段 | 说明 | +|----|:-----------------|:-------------------------------------------------|:-----------------| +| 1 | `*` | - | 通配符，表示输出数据库中所有字段 | +| 2 | `find` | `country,province,city,isp` | 查询操作 | +| 3 | `chinaCity` | `country,province,city,isp\|country=!中国:country` | 中国城市 | +| 4 | `provinceAndISP` | `province,isp\|country=!中国:` | 中国省份和运营商 | +| 5 | `cn` | `country\|country=中国:country='CN'\|country='OV'` | 中国国家 | + +### use_db_fields + +确定是否使用数据库自带的字段名称，布尔值参数。一般与 JSON 格式输出配合使用。 + +当设置为 `true` 时，输出将不使用通用字段映射，而是直接显示数据库中的原始字段名。 + +### rewrite_files + +此参数允许您指定一个或多个文件，这些文件包含了用于改写数据库条目的规则，文件之间使用 `,` 分隔。 + +此功能可以帮助修正数据库中的错误或不精确的数据，或者将数据格式化为所需的形式。 + +默认情况下，将从项目的 `internal/data` 目录自动载入内置的改写文件。 + +**改写文件格式** + +改写文件遵循特定的格式，每一行包含一个匹配条件和一个替换动作，由制表符 (`\t`) 分隔： + +```shell +\t\n + @ - 使用 URL 查询字符串格式，定义需要匹配的数据库字段和值。 + @ - 同样使用 URL 查询字符串格式，指定字段的新值。 + +举例： + # 将省份信息为 "内蒙古" 的记录的省份字段改写为 "内蒙" + province=内蒙古 province=内蒙 + + # 如果 ASN 为 4134，将 ISP 字段改写为 "电信" + asn=4134 isp=电信 + + # 对于国家字段是 "辽宁省抚顺市" 的记录，将其拆分为国家 "中国"、省份 "辽宁" 和城市 "抚顺"（来自 qqwry.dat (´･_･`)） + country=辽宁省抚顺市 country=中国&province=辽宁&city=抚顺 +``` + +在这些例子中，我们可以看到如何使用改写规则来修改数据。这可以用于纠正错误的数据，合并或拆分字段，或者转换字段值以适应特定的输出格式需求。 + +**使用改写文件** + +可以通过以下方式指定改写文件： + +```shell +$ ips config set rewrite_files "/path/to/rewrite1.txt,/path/to/rewrite2.txt" +``` + +此命令将指定两个改写文件，ips 将在处理数据库查询时应用这些文件中的规则。 + +通过使用改写文件，您可以确保即使源数据库包含了不精确的信息，输出数据也能符合要求。 + +### output_type + +指定命令输出信息的格式，字符串字段。它可以根据您的需要设置为不同的类型，以便在不同的环境下使用。默认值为 `text`。 可选值有： + +- `text`: 以纯文本格式输出查询结果。 +- `json`: 以 JSON 格式输出查询结果。 +- `alfred`: 以 Alfred Workflow 所需的格式输出查询结果。 + +### text_format + +当您使用文本输出时，此参数定义了输出的具体格式，字符串参数。 + +您可以自定义这个格式，以便在输出结果时展示有用的信息。默认值为 `%origin [%values]`。 当前支持的格式变量有： + +- `%origin`: 表示原始的查询数据。 +- `%values`: 表示查询结果的字段值。 + +### text_values_sep + +当您使用文本输出时，此参数定义了多个字段值之间的分隔符，字符串参数。默认值为 ` `(空格)。 + +### json_indent + +控制 JSON 格式输出时是否进行缩进，以提高可读性，布尔值参数。默认值为 `false`。 + +### dp_fields + +功能与 `fields` 字段类似，在进行数据库的转存或打包操作时，此参数允许您选择哪些字段将被包含在最终的数据中。默认值为空，代表包含所有字段。 + +### dp_rewriter_files + +功能与 `rewrite_files` 字段类似，此参数允许您指定用于转存或打包操作的改写文件列表。默认值为空。 + +### reader_option + +一些数据库格式提供了额外的读取选项，通过此参数可以在初始化数据库读取器时进行设置，用以影响读取操作的行为。 + +例如 `mmdb` 数据库的 `disable_extra_data` 等，具体功能请查阅数据库文档。 + +### writer_option + +一些数据库格式提供了额外的写入选项，通过此参数可以在初始化数据库写入器时进行设置，用以影响写入操作的行为。 + +例如 `mmdb` 数据库的 `select_languages` 等，具体功能请查阅数据库文档。 + +### myip_count + +在查询本机 IP 地址时，此参数定义了返回相同 IP 地址的最小探测器数量。默认值为 `3`。 + +### myip_timeout_s + +此参数设置查询本机 IP 地址时，每个探测器的超时时间（以秒为单位）。默认值为 `10` 秒。 + +### addr + +在启动 IPS 服务时，此参数定义了服务监听的地址。默认值为 `0.0.0.0:6860`，表示在所有网络接口的 `6860` 端口上监听。 + diff --git a/docs/config_en.md b/docs/config_en.md new file mode 100644 index 0000000..e7b8824 --- /dev/null +++ b/docs/config_en.md @@ -0,0 +1,335 @@ +# IPS Configuration Documentation + + +* [IPS Configuration Documentation](#ips-configuration-documentation) + * [Introduction](#introduction) + * [Configuration Types](#configuration-types) + * [Working Directory](#working-directory) + * [Configuration Loading Logic](#configuration-loading-logic) + * [Configuration Command](#configuration-command) + * [Viewing Current Configuration](#viewing-current-configuration) + * [Modifying Configuration Parameters](#modifying-configuration-parameters) + * [Removing Configuration Parameters](#removing-configuration-parameters) + * [Resetting Configuration Parameters](#resetting-configuration-parameters) + * [Configuration Parameters](#configuration-parameters) + * [lang](#lang) + * [ipv4_file](#ipv4file) + * [ipv4_format](#ipv4format) + * [ipv6_file](#ipv6file) + * [ipv6_format](#ipv6format) + * [fields](#fields) + * [use_db_fields](#usedbfields) + * [rewrite_files](#rewritefiles) + * [output_type](#outputtype) + * [text_format](#textformat) + * [text_values_sep](#textvaluessep) + * [json_indent](#jsonindent) + * [dp_fields](#dpfields) + * [dp_rewriter_files](#dprewriterfiles) + * [reader_option](#readeroption) + * [writer_option](#writeroption) + * [myip_count](#myipcount) + * [myip_timeout_s](#myiptimeouts) + * [addr](#addr) + + +## Introduction + +In order to meet the individual needs of different users and simplify the process of querying, transferring, and packaging IP geolocation databases, IPS provides a flexible configuration system. + +Through this system, users can customize the behavior of IPS, including but not limited to specifying the IP database, output format, query fields, etc. + +Configuration parameters affect the efficiency of using IPS and the output of results. Reasonable configurations can improve query speed, optimize content output, and make transfer and packaging operations more in line with users' actual needs. + +## Configuration Types + +The configuration of IPS mainly falls into two categories: + +- **Command Line Arguments**: Specified directly in the command line, suitable for one-time tasks or to override default settings. +- **Configuration Files**: Persistently saved in the `ips.json` file in the IPS working directory, suitable for routine operations and personalized settings. + +## Working Directory + +By default, IPS treats the `.ips` folder in the user's HOME directory as the working directory, with the path `${HOME}/.ips`. This directory is responsible for storing configuration files and IP database files downloaded by IPS. + +If the HOME directory is unavailable, IPS will use the system's temporary folder `${TEMP}/.ips` as a fallback. + +Users can specify a custom working directory path using the `IPS_DIR` environment variable. + +## Configuration Loading Logic + +IPS automatically loads the configuration file from the working directory at startup. If the configuration file does not exist or some parameters are missing, IPS will use the built-in default configuration and create or update the configuration file. + +It should be noted that command line arguments will take precedence over settings in the configuration file, providing users with a more flexible configuration method. + +## Configuration Command + +IPS provides the ability to view and modify configuration parameters through the `ips config` command. It aims to offer users a safer and more convenient way to manage the configuration of IPS than directly editing the configuration file. + +### Viewing Current Configuration + +Running `ips config` without any additional parameters will output the current tool's configuration parameters. This is a quick method to check the current settings and can also be used to confirm whether previous modifications have taken effect. + + +```shell +# Output current configuration parameters +$ ips config +IPS CONFIG ==================================================================== + +ips dir: [/Users/sarv/.ips] +ipv4_file(ipv4): [ipv4.awdb] +ipv6_file(ipv6): [GeoLite2-City.mmdb] +fields: [country,province,city,isp] +text_format: [%origin [%values] ] +text_values_sep: [ ] + +=============================================================================== +... ... +``` + +### Modifying Configuration Parameters + +The `ips config set` subcommand can be used to modify individual configuration parameters. After a successful modification, IPS will display a confirmation message. + +```shell +# Set the IPv4 database file path to the specified file +$ ips config set ipv4 ~/path/to/ipv4.db +INFO[2023-11-02T13:08:01+08:00] set ipv4_file: [/Users/sarv/path/to/ipv4.db] success + +# Confirm that the parameter modification was successful +$ ips config +IPS CONFIG ==================================================================== + +ips dir: [/Users/sarv/.ips] +ipv4_file(ipv4): [/Users/sarv/path/to/ipv4.db] # Modification successful +ipv6_file(ipv6): [GeoLite2-City.mmdb] +... ... +``` + +### Removing Configuration Parameters + +The `ips config unset` allows users to remove a configuration parameter, setting its value to empty. Please note that this will not revert to the default value but will require explicit specification or allow IPS to use the default setting in subsequent operations. + +```shell +# Remove the configuration of the IPv4 database file path +$ ips config unset ipv4 +INFO[2023-11-02T13:09:15+08:00] unset ipv4_file success +``` + +### Resetting Configuration Parameters + +To restore all configuration parameters to their default values, the `ips config reset` subcommand can be used. This will discard all user-defined configurations and restore IPS to its initial state. + +```shell +# Reset all configuration parameters to default values +$ ips config reset +INFO[2023-11-02T13:12:21+08:00] reset config success +``` + +## Configuration Parameters + +IPS offers a wide range of configuration parameters to suit different usage scenarios. Below is a detailed introduction to all available configuration parameters, including their functions and default values. + +### lang + +Sets the language of the output information, a string parameter. The default is `zh-CN` (Chinese), with the following list of supported languages: + +| Number | Language | Code | +|--------|:-----------|:--------| +| 1 | English | `en` | +| 2 | Chinese | `zh-CN` | +| 3 | Russian | `ru` | +| 4 | Japanese | `ja` | +| 5 | German | `de` | +| 6 | French | `fr` | +| 7 | Spanish | `es` | +| 8 | Portuguese | `pt-BR` | +| 9 | Persian | `fa` | +| 10 | Korean | `ko` | + +It is important to note that the translation data comes from [GeoNames.org](https://geonames.org). For multilingual IP databases, such as `mmdb`, the translation data in the database will be used directly. + +### ipv4_file + +Specifies the database file used for IPv4 address queries, a string parameter, with the default value `qqwry.dat`. + +### ipv4_format + +Specifies the format of the IPv4 database file, a string parameter. + +When the database file suffix is insufficient to determine the file format, it is used to specify the format of the IPv4 database. Usually, it is not necessary to set this. + +### ipv6_file + +Specifies the database file used for IPv6 address queries, a string parameter, with the default value `zxipv6wry.db`. + +### ipv6_format + +Specifies the format of the IPv6 database file, a string parameter. + +When the database file suffix is insufficient to determine the file format, it is used to specify the format of the IPv6 database. Usually, it is not necessary to set this. + +### fields + +Defines which fields to display in the query results, a string parameter. The default value is `country,province,city,isp`. This parameter supports various advanced usages: + +**Generic Field Mapping** + +In addition to using database fields directly, `fields` allows you to use generic fields, which means you can refer to the same type of data in different databases that may have different names using one field name. + +For example, the generic field `country` represents country information and may be represented as `country`, `country_name`, `countryName`, etc., in different databases. + +The current generic fields are: + +| Number | Field | Description | +|--------|:-----------------|:-----------------------------------| +| 1 | `country` | Country | +| 2 | `province` | Province | +| 3 | `city` | City | +| 4 | `isp` | ISP | +| 5 | `asn` | Autonomous System Number | +| 6 | `continent` | Continent | +| 7 | `utcOffset` | UTC Offset | +| 8 | `latitude` | Latitude | +| 9 | `longitude` | Longitude | +| 10 | `chinaAdminCode` | China Administrative Division Code | + +Database fields refer to the unique fields in different databases, such as the `subdivisions` field in `mmdb`, the `region` field in `ip2region`, etc. + +**Conditional Field Selection** + +`fields` also supports conditional field selection. This allows you to change the output fields based on the values of specific fields in the query results. + +Conditions use URL query string format and support basic logical operations, such as `country=中国`, `country=!中国` (not China), `country=中国/美国` (China or USA). + +If no condition matches, you can specify a default list of fields. This is done by adding a list of fields without conditions at the end of the conditional selection statement. + +```shell +[|:|:|] + @ - List of output fields + @ - Matching condition + @ - Default list of output fields + +Example: + # When the queried IP address is located in China, output the country,province,city,isp fields + # For IP addresses outside of China, only output the country field + "country,province,city,isp|country=!中国:country" +``` + +**Magic Variables** + +fields supports the use of specific magic variables to quickly select a set of fields. The currently supported magic variables are: + +| Number | Magic Variable | Actual Represented Fields | Description | +|--------|:-----------------|:-------------------------------------------------|:------------------------------------------------| +| 1 | `*` | - | Wildcard, represents all fields in the database | +| 2 | `find` | `country,province,city,isp` | Query operation | +| 3 | `chinaCity` | `country,province,city,isp\|country=!中国:country` | Chinese city | +| 4 | `provinceAndISP` | `province,isp\|country=!中国:` | Chinese province and ISP | +| 5 | `cn` | `country\|country=中国:country='CN'\|country='OV'` | Chinese country | + + +### use_db_fields + +Decide whether to use the field names that come with the database, a boolean parameter. It is generally used in combination with JSON format output. + +When set to `true`, the output will not use common field mapping but will directly display the original field names in the database. + +### rewrite_files + +This parameter allows you to specify one or multiple files containing rules for rewriting database entries, separated by `,`(commas). + +This feature can help correct errors or inaccuracies in the database or format the data into the desired form. + +By default, the built-in rewrite files will be automatically loaded from the project's `internal/data` directory. + +**Rewrite File Format** + +Rewrite files follow a specific format, each line containing a matching condition and a replacement action, separated by a tab (`\t`): + +```shell +\t\n + @ - Uses URL query string format, defining the database fields and values to match. + @ - Also uses URL query string format, specifying the new values for the fields. + +Example: + # Rewrite the province field of records with the province information "内蒙古" to "内蒙" + province=内蒙古 province=内蒙 + + # If ASN is 4134, rewrite the ISP field to "电信" + asn=4134 isp=电信 + + # For records with the country field as "辽宁省抚顺市", split it into country "中国", province "辽宁" and city "抚顺" (from qqwry.dat (´･_･`)) + country=辽宁省抚顺市 country=中国&province=辽宁&city=抚顺 +``` + +In these examples, we can see how to use rewrite rules to modify data. This can be used to correct erroneous data, merge or split fields, or convert field values to meet specific output format requirements. + +**Using Rewrite Files** + +Rewrite files can be specified in the following way: + +```shell +$ ips config set rewrite_files "/path/to/rewrite1.txt,/path/to/rewrite2.txt" +``` + +This command will specify two rewrite files, and IPS will apply the rules in these files when processing database queries. + +By using rewrite files, you can ensure that even if the source database contains inaccurate information, the output data will meet the requirements. + +### output_type + +Specify the format of the command output information, a string field. It can be set to different types according to your needs, so that it can be used in different environments. The default value is `text`. The options are: + +- `text`: Outputs the query results in plain text format. +- `json`: Outputs the query results in JSON format. +- `alfred`: Outputs the query results in the format required by Alfred Workflow. + +### text_format + +When using text output, this parameter defines the specific format of the output, a string parameter. + +You can customize this format to display useful information when outputting results. The default value is `%origin [%values]`. The current supported format variables are: + +- `%origin`: Represents the original query data. +- `%values`: Represents the field values of the query results. + +### text_values_sep + +When using text output, this parameter defines the separator between multiple field values, a string parameter. The default value is a ` `(space). + +### json_indent + +Controls whether to indent JSON format output to improve readability, a boolean parameter. The default value is `false`. + +### dp_fields + +Similar to the `fields` parameter, this parameter allows you to choose which fields will be included in the final data during the database storage or packaging operation. The default value is empty, which means all fields are included. + +### dp_rewriter_files + +Similar to the `rewrite_files` parameter, this parameter allows you to specify a list of rewrite files for storage or packaging operations. The default value is empty. + +### reader_option + +Some database formats provide additional reading options, which can be set during the initialization of the database reader through this parameter to affect the behavior of the reading operation. + +For example, `mmdb` database's `disable_extra_data` and so on, please refer to the database documentation for specific functions. + +### writer_option + +Some database formats provide additional writing options, which can be set during the initialization of the database writer through this parameter to affect the behavior of the writing operation. + +For example, `mmdb` database's `select_languages` and so on, please refer to the database documentation for specific functions. + +### myip_count + +When querying the local IP address, this parameter defines the minimum number of detectors that return the same IP address. The default value is `3`. + +### myip_timeout_s + +This parameter sets the timeout for each detector when querying the local IP address, in seconds. The default value is `10` seconds. + +### addr + +When starting the IPS service, this parameter defines the address where the service listens. The default value is `0.0.0.0:6860`, indicating that it listens on port `6860` on all network interfaces. diff --git a/docs/download.md b/docs/download.md new file mode 100644 index 0000000..fa0319d --- /dev/null +++ b/docs/download.md @@ -0,0 +1,78 @@ +# IPS 下载命令说明 + + +* [IPS 下载命令说明](#ips-下载命令说明) + * [简介](#简介) + * [使用方法](#使用方法) + * [命令语法](#命令语法) + * [预定义的数据库列表](#预定义的数据库列表) + * [示例](#示例) + * [下载预定义数据库](#下载预定义数据库) + * [使用自定义 URL 下载数据库并设置为默认数据库](#使用自定义-url-下载数据库并设置为默认数据库) + * [注意事项](#注意事项) + + +## 简介 + +`ips download` 命令用于帮助用户简化 IP 地理位置数据库的获取和更新过程。 + +需要注意的是，IPS 并不拥有这些数据库的版权，所有的数据库链接均来自于社区用户的分享或是官方提供的免费版本。 + +IPS 提供这些链接是为了便利用户，但不对数据库内容或版权负责。 + +如果版权所有者认为不应该在 IPS 中提供这些链接，请联系 IPS 的作者以便及时移除。 + +## 使用方法 + +`ips download` 支持直接通过预定义的 URL 下载数据库，用户也可以提供自定义的 URL 来下载所需的数据库文件。 + +下载完成后，可以通过 `ips config` 命令配置新下载的数据库文件路径。 + +## 命令语法 + +```shell +ips download [database_name] [custom_url] +``` + +- `database_name`：预定义的数据库名称。 +- `custom_url`：（可选）自定义的下载链接，如果未使用预定义的文件，则可从中下载数据库文件。 + +## 预定义的数据库列表 + +IPS 维护一个包含流行 IP 地理位置数据库的列表，以下是可供下载的数据库： + +| 数据库名称 | 格式 | 下载地址 | 说明 | +|:--------------------|:----------|:-------------------------------------------------------------------------------------------|:-----------------| +| GeoLite2-City.mmdb | mmdb | [Link](https://git.io/GeoLite2-City.mmdb) | MaxMind 免费版数据库 | +| city.free.ipdb | ipdb | [Link](https://raw.githubusercontent.com/ipipdotnet/ipdb-go/master/city.free.ipdb) | IPIP.net 免费版数据库 | +| dbip-asn-lite.mmdb | mmdb | [Link](https://download.db-ip.com/free/dbip-asn-lite-2023-10.mmdb.gz) | db-ip 免费版数据库 | +| dbip-city-lite.mmdb | mmdb | [Link](https://download.db-ip.com/free/dbip-city-lite-2023-10.mmdb.gz) | db-ip 免费版数据库 | +| ip2region.xdb | ip2region | [Link](https://raw.githubusercontent.com/lionsoul2014/ip2region/master/data/ip2region.xdb) | ip2region 免费版数据库 | +| qqwry.dat | qqwry | [Link](https://github.com/metowolf/qqwry.dat/releases/download/20231011/qqwry.dat) | 纯真数据库(社区分享) | +| zxipv6wry.db | zxinc | [Link](https://raw.githubusercontent.com/ZX-Inc/zxipdb-python/main/data/ipv6wry.db) | ip.zxinc.org 数据库 | + +这些数据库均来源于互联网，部分数据库会定期进行更新。您可以通过提供的链接访问和下载最新版本的数据库。 + +## 示例 + +### 下载预定义数据库 + +```shell +# 下载 IPIP.net 提供的免费城市数据库 +ips download city.free.ipdb +``` + +### 使用自定义 URL 下载数据库并设置为默认数据库 + +```shell +# 通过自定义 URL 下载数据库文件 +ips download city.ipdb https://foo.com/city.ipdb + +# 设置为默认数据库 +ips config set ipv4 city.ipdb +``` + +## 注意事项 + +- 下载目录为 IPS 工作目录，关于工作目录的定义可翻阅 [IPS 配置说明](./config.md#工作目录)。 +- 下载数据库后，需要在 IPS 的配置中指定数据库文件路径，以便使用新数据库进行 IP 查询。 \ No newline at end of file diff --git a/docs/download_en.md b/docs/download_en.md new file mode 100644 index 0000000..366051e --- /dev/null +++ b/docs/download_en.md @@ -0,0 +1,66 @@ +# IPS Download Command Documentation + +## Introduction + +The `ips download` command is designed to help users simplify the process of acquiring and updating IP geolocation databases. + +It is important to note that IPS does not own the copyrights of these databases. All database links are shared by community users or are official free versions. + +IPS provides these links for user convenience but is not responsible for the content or copyright of the databases. + +If copyright owners believe these links should not be provided within IPS, please contact the author of IPS for prompt removal. + +## Usage + +`ips download` supports direct downloading of databases through predefined URLs. Users can also provide custom URLs to download the required database files. + +After downloading, the new database file path can be configured using the ips config command. + +## Command Syntax + +```shell +ips download [database_name] [custom_url] +``` + +- `database_name`: The predefined name of the database. +- `custom_url`: (Optional) A custom download link to download database files if not using a predefined one. + +## Predefined Database List + +IPS maintains a list of popular IP geolocation databases for download. Below is the list of available databases: + +| Database Name | Format | Download Link | Description | +|:--------------------|:-------|:-------------------------------------------------------------------------------------------|:---------------------------| +| GeoLite2-City.mmdb | mmdb | [Link](https://git.io/GeoLite2-City.mmdb) | MaxMind free edition | +| city.free.ipdb | ipdb | [Link](https://raw.githubusercontent.com/ipipdotnet/ipdb-go/master/city.free.ipdb) | IPIP.net free edition | +| dbip-asn-lite.mmdb | mmdb | [Link](https://download.db-ip.com/free/dbip-asn-lite-2023-10.mmdb.gz) | db-ip free edition | +| dbip-city-lite.mmdb | mmdb | [Link](https://download.db-ip.com/free/dbip-city-lite-2023-10.mmdb.gz) | db-ip free edition | +| ip2region.xdb | xdb | [Link](https://raw.githubusercontent.com/lionsoul2014/ip2region/master/data/ip2region.xdb) | ip2region free edition | +| qqwry.dat | dat | [Link](https://github.com/metowolf/qqwry.dat/releases/download/20231011/qqwry.dat) | CZ88.NET database (shared) | +| zxipv6wry.db | db | [Link](https://raw.githubusercontent.com/ZX-Inc/zxipdb-python/main/data/ipv6wry.db) | ip.zxinc.org database | + +These databases are sourced from the Internet, and some are regularly updated. You can access and download the latest versions of the databases via the provided links. + +## Examples + +### Downloading a Predefined Database + +```shell +# Download the free city database provided by IPIP.net +ips download city.free.ipdb +``` + +Downloading a Database Using a Custom URL and Setting as Default + +```shell +# Download a database file using a custom URL +ips download city.ipdb https://foo.com/city.ipdb + +# Set as the default database +ips config set ipv4 city.ipdb +``` + +## Notes + +- The download directory is the IPS working directory. For the definition of the working directory, please refer to [IPS Configuration Documentation](./config_en.md#working-directory). +- After downloading a database, it is necessary to specify the database file path in the IPS configuration to use the new database for IP queries. \ No newline at end of file diff --git a/docs/dump.md b/docs/dump.md new file mode 100644 index 0000000..964fd76 --- /dev/null +++ b/docs/dump.md @@ -0,0 +1,74 @@ +# IPS 转存命令说明 + + +* [IPS 转存命令说明](#ips-转存命令说明) + * [简介](#简介) + * [使用方法](#使用方法) + * [命令语法](#命令语法) + * [示例](#示例) + * [转存 IP 数据库内容到标准输出流](#转存-ip-数据库内容到标准输出流) + * [转存 IP 数据库内容到文本文件](#转存-ip-数据库内容到文本文件) + * [自定义导出字段](#自定义导出字段) + * [设置输出语言和改写规则](#设置输出语言和改写规则) + * [注意事项](#注意事项) +> + +## 简介 + +`ips dump` 命令允许用户从 IP 数据库文件中导出数据到文本文件中，用于数据分析或其他处理。此命令支持多种数据库格式，并允许自定义输出的数据字段。 + +## 使用方法 + +使用 `ips dump` 命令，可以指定输入文件、输入格式、导出字段等选项来执行数据导出操作。 + +## 命令语法 + +```shell +ips dump -i inputFile [--input-format] [-o outputFile] [flags] +``` + +- `-i, --input-file string`：指定输入 IP 数据库文件的路径。必填项。 +- `--input-format string`：指定输入 IP 数据库文件的格式。默认为自动检测。 +- `--input-option string`：数据库读取器指定选项。具体信息请查阅数据库文档。 +- `-o, --output-file string`：指定转存文件的路径。不指定转存文件时，输出到标准输出流。 +- `--lang string`：设置输出信息的语言。默认为 `zh-CN` (中文)。 +- `-f, --fields string`：指定从输入文件中获取的字段。默认为所有字段。参数详细解释请参考 [IPS 配置说明](./config.md#fields)。 +- `-r, --rewrite-files string`：指定需要载入的改写文件列表。参数详细解释请参考 [IPS 配置说明](./config.md#rewritefiles)。 + +## 示例 + +### 转存 IP 数据库内容到标准输出流 + +```shell +# 从 GeoLite2-City.mmdb 数据库文件导出数据到标准输出流 +ips dump -i GeoLite2-City.mmdb +``` + +### 转存 IP 数据库内容到文本文件 + +```shell +# 从 GeoLite2-City.mmdb 数据库文件导出数据到 geoip.txt +ips dump -i GeoLite2-City.mmdb -o geoip.txt +``` + +### 自定义导出字段 + +```shell +# 从数据库文件中仅导出国家和城市字段 +ips dump -i GeoLite2-City.mmdb -o geoip.txt --fields "country,city" +``` + +### 设置输出语言和改写规则 + +```shell +# 设置导出数据的语言为英文，并应用改写规则 +ips dump -i GeoLite2-City.mmdb -o geoip.txt --lang en -r rewrite_rules.txt +``` + +## 注意事项 + +- 确保 `--input-file` 指向的数据库文件是存在且有效的。 +- 如果指定 `--input-format`，请确认格式与文件相符。 +- 使用 `--fields` 可以减少输出的数据量，仅导出需要的字段。 +- `--lang` 选项可以根据需要设置输出数据的语言，通常用于多语言数据库。 +- `--rewrite-files` 可以在导出数据前应用自定义的重写规则，以纠正数据库中的错误或进行数据定制。 diff --git a/docs/dump_en.md b/docs/dump_en.md new file mode 100644 index 0000000..f77eb63 --- /dev/null +++ b/docs/dump_en.md @@ -0,0 +1,75 @@ +# IPS Dump Command Documentation + + +* [IPS Dump Command Documentation](#ips-dump-command-documentation) + * [Introduction](#introduction) + * [Usage](#usage) + * [Command Syntax](#command-syntax) + * [Examples](#examples) + * [Dump IP Database Contents to Standard Output](#dump-ip-database-contents-to-standard-output) + * [Dump IP Database Contents to a Text File](#dump-ip-database-contents-to-a-text-file) + * [Customize Export Fields](#customize-export-fields) + * [Set Output Language and Rewrite Rules](#set-output-language-and-rewrite-rules) + * [Notes](#notes) +> + +## Introduction + +The `ips dump` command allows users to export data from IP database files to plain text files for data analysis or other processing. This command supports multiple database formats and allows for customization of the output data fields. + + +## Usage + +The `ips dump` command can be used to specify input files, input formats, export fields, and other options to perform data export operations. + +## Command Syntax + +```shell +ips dump -i inputFile [--input-format] [-o outputFile] [flags] +``` + +- `-i, --input-file string`：Specifies the path to the input IP database file. Required. +- `--input-format string`：Specifies the format of the input IP database file. Default is auto-detection. +- `--input-option string`：Specifies options for the database reader. For more information, refer to the database documentation. +- `-o, --output-file string`：Specifies the path to the dump file. When not specified, outputs to the standard output stream. +- `--lang string`：Sets the language for the output information. Default is `zh-CN` (Chinese). +- `-f, --fields string`：Specifies the fields to be extracted from the input file. Default is all fields. For a detailed explanation of the parameter, refer to [IPS Configuration Documentation](./config_en.md#fields)。 +- `-r, --rewrite-files string`：Specifies the list of rewrite files to load. For a detailed explanation of the parameter, refer to [IPS Configuration Documentation](./config_en.md#rewritefiles)。 + +## Examples + +### Dump IP Database Contents to Standard Output + +```shell +# Export data from the GeoLite2-City.mmdb database file to the standard output stream +ips dump -i GeoLite2-City.mmdb +``` + +### Dump IP Database Contents to a Text File + +```shell +# Export data from the GeoLite2-City.mmdb database file to geoip.txt +ips dump -i GeoLite2-City.mmdb -o geoip.txt +``` + +### Customize Export Fields + +```shell +# Export only the country and city fields from the database file +ips dump -i GeoLite2-City.mmdb -o geoip.txt --fields "country,city" +``` + +### Set Output Language and Rewrite Rules + +```shell +# Set the output data language to English and apply rewrite rules +ips dump -i GeoLite2-City.mmdb -o geoip.txt --lang en -r rewrite_rules.txt +``` + +## Notes + +- Ensure that the `--input-file` points to an existing and valid database file. +- If `--input-format` is specified, make sure it matches the file format. +- Using `--fields` can reduce the amount of data output, exporting only the necessary fields. +- The `--lang` option can set the language of the output data as needed, typically used for multilingual databases. +- `--rewrite-files` can be used to apply custom rewrite rules before exporting data, to correct errors in the database or for data customization. \ No newline at end of file diff --git a/docs/format_ipdb.md b/docs/format_ipdb.md new file mode 100644 index 0000000..2801b55 --- /dev/null +++ b/docs/format_ipdb.md @@ -0,0 +1,94 @@ +# IPDB 格式数据库 + + +* [IPDB 格式数据库](#ipdb-格式数据库) + * [简介](#简介) + * [格式分析](#格式分析) + * [MetaData 分析](#metadata-分析) + * [NodeChunk 分析](#nodechunk-分析) + * [DataChunk 分析](#datachunk-分析) + * [查询操作](#查询操作) + * [打包流程](#打包流程) + + +## 简介 + +IPDB 数据库是由 [IPIP.net](https://www.ipip.net/) 设计并使用的一种 IP 数据库格式，以体积小、查询效率高、支持多语言等特点而知名。（高老师牛逼～） + +## 格式分析 + +```shell + +--------------------------------+--------------------------------+ + | MetaData Length (4byte) | MetaData (Json Format) | + +--------------------------------+--------------------------------+ + | Node Chunk (Prefix Tree / Trie) | + +--------------------------------+--------------------------------+ + | Data Chunk | + +--------------------------------+--------------------------------+ +``` + +* 文件分为三个部分：MetaData、NodeChunk、DataChunk。 + +### MetaData 分析 + +MetaData 是一个 JSON 对象，包含数据库构建信息和查询所需的元数据。以下是一个示例： + +```shell +{ + "build": 1632971142, // 构建时间 + "ip_version": 1, // IP库版本 IPv4:0x1 IPv6:0x2 + "languages": { + "CN": 0 // 语言 & 字段偏移量 + }, + "node_count": 8705098, // Node数量 + "total_size": 90028407, // NodeChunk+DataChunk 数据大小 + "fields": [ // DataChunk中每组数据的字段 + "country_name", + "region_name", + "city_name", + "owner_domain", + "isp_domain", + "latitude", + "longitude", + "timezone", + "utc_offset", + "china_admin_code", + "idd_code", + "country_code", + "continent_code" + ] +} +``` + +## NodeChunk 分析 + +NodeChunk 由前缀树（字典树）构成。每个 Node 为 8 字节，存储到下一个节点的偏移量。如果偏移量超过节点数，则跳转到 DataChunk，表示找到了结果。 + +### DataChunk 分析 + +DataChunk 存储 IP 数据库数据。相同的数据仅存储一次，以减少冗余。 + +```shell + +--------------------------------+--------------------------------+--------------------------------+ + | Data Length (2byte) | Data Fields(\t\t\t\t\t) | + +--------------------------------+--------------------------------+--------------------------------+ + | Data Length (2byte) | Data Fields(\t\t\t\t\t) | + +--------------------------------+--------------------------------+--------------------------------+ +``` + +* DataChunk 在数据块中，数据分为长度和数据两部分。 +* 数据部分使用 `\t` 分隔字段，在多语言版本的数据库中使用字段偏移返回不同语言的数据。 + +## 查询操作 + +* CIDR 地址是一种结合了 IP 地址和子网掩码的网段描述方式，如 10.0.0.1/8 表示一个 8 位子网掩码（255.0.0.0）。CIDR 网段内的所有 IP 在子网掩码部分完全相同。 +* 将 IP 地址视为一个 32位/128位 的二进制字符串，在节点块中使用前缀树从前往后查询，一旦找到 CIDR 匹配，就跳转到数据块返回相应数据。 +* 更多的 CIDR 分组会导致更大的节点数。 +* CIDR 不得相互包含，嵌套的 CIDR（如 10.0.0.1/8 和 10.0.0.1/16）可能会因为先匹配到的原因而阻止进一步匹配。 +* 关于查询过程的详细解释，请参考论文 [IPv4 route lookup on Linux](https://vincent.bernat.ch/en/blog/2017-ipv4-route-lookup-linux)。 + +## 打包流程 + +* 构建前缀树，并按照加载顺序将不同的数据集放入数据块。 +* 根据 IPv6 的规范构建前缀树，IPv4 数据需要填充前 96 位的子网数据，即 80 位的 0 和 16 位的 1，对应于 IPv6 的映射地址（::FFFF:）。查询 IPv4 时，这允许快速偏移到 96 位掩码位置开始查询。 +* 理论上，ipdb 格式数据库支持将 IPv4 和 IPv6 数据存储在同一个文件中，但确保 ::FFFF: 的路径上没有其他 CIDR 记录，以保持 IPv4 查询路径畅通（修改查询 SDK 可以更好地支持同时查询 IPv4/IPv6）。 diff --git a/docs/format_ipdb_en.md b/docs/format_ipdb_en.md new file mode 100644 index 0000000..2f244cb --- /dev/null +++ b/docs/format_ipdb_en.md @@ -0,0 +1,94 @@ +# IPDB Database Format + + +* [IPDB Database Format](#ipdb-database-format) + * [Introduction](#introduction) + * [Format Analysis](#format-analysis) + * [MetaData Analysis](#metadata-analysis) + * [NodeBlock Analysis](#nodeblock-analysis) + * [DataBlock Analysis](#datablock-analysis) + * [Query Operation](#query-operation) + * [Packaging Process](#packaging-process) + + +## Introduction + +The IPDB database is an IP database format designed and utilized by [IPIP.net](https://www.ipip.net/), renowned for its compact size, high query efficiency, and multi-language support. + +## Format Analysis + +```shell + +--------------------------------+--------------------------------+ + | MetaData Length (4byte) | MetaData (Json Format) | + +--------------------------------+--------------------------------+ + | Node Chunk (Prefix Tree / Trie) | + +--------------------------------+--------------------------------+ + | Data Chunk | + +--------------------------------+--------------------------------+ +``` + +* The file is divided into three parts: metadata, node block, and data block. + +## MetaData Analysis + +Metadata is a JSON object containing the database build information and metadata required for querying. Below is an example: + +```shell +{ + "build": 1632971142, // Build time + "ip_version": 1, // IP database version (IPv4: 0x1, IPv6: 0x2) + "languages": { + "CN": 0 // Languages and field offsets + }, + "node_count": 8705098, // Number of nodes + "total_size": 90028407, // Total size of the node block + data block + "fields": [ // Fields for each data set in the data block + "country_name", + "region_name", + "city_name", + "owner_domain", + "isp_domain", + "latitude", + "longitude", + "timezone", + "utc_offset", + "china_admin_code", + "idd_code", + "country_code", + "continent_code" + ] +} +``` + +## NodeBlock Analysis + +The node block consists of a prefix tree (trie). Each node is 8 bytes and stores the offset to the next node. If the offset exceeds the number of nodes, it jumps to the data block, indicating a result has been found. + +## DataBlock Analysis + +The data block stores IP database data. Identical data is stored only once to reduce redundancy. + +```shell + +--------------------------------+--------------------------------+--------------------------------+ + | Data Length (2byte) | Data Fields(\t\t\t\t\t) | + +--------------------------------+--------------------------------+--------------------------------+ + | Data Length (2byte) | Data Fields(\t\t\t\t\t) | + +--------------------------------+--------------------------------+--------------------------------+ +``` + +* In the data block, data is split into two parts: length and data. +* The data part uses `\t` to separate fields. In multi-language versions of the database, different language data is returned using field offsets. + +## Query Operation + +* A CIDR address is a way of describing a network segment that combines an IP address with a subnet mask, e.g., 10.0.0.1/8 represents an 8-bit subnet mask (255.0.0.0). All IPs within a CIDR segment have identical subnet mask parts. +* IP addresses are treated as 32-bit/128-bit binary strings. In the node block, the prefix tree is used to search from the beginning, and once a CIDR match is found, it jumps to the data block to return the corresponding data. +* More CIDR groupings result in a larger number of nodes. +* CIDRs should not overlap; nested CIDRs (like 10.0.0.1/8 and 10.0.0.1/16) may be precluded from further matching due to earlier matches. +* For a detailed explanation of the query process, refer to the paper [IPv4 route lookup on Linux](https://vincent.bernat.ch/en/blog/2017-ipv4-route-lookup-linux). + +## Packaging Process + +* Build the prefix tree and place different datasets into the data block in load order. +* Prefix trees are built according to IPv6 specifications; IPv4 data needs to fill in 96 bits of subnet data at the front, i.e., 80 bits of 0 and 16 bits of 1, corresponding to the IPv6 mapped address (::FFFF:). This allows fast offset to the 96-bit mask position for IPv4 querying. +* In theory, the ipdb format database can store both IPv4 and IPv6 data in the same file, but ensure that no other CIDR records exist on the ::FFFF: path to keep the IPv4 query path clear (modifying the query SDK can better support simultaneous IPv4/IPv6 queries). \ No newline at end of file diff --git a/docs/myip.md b/docs/myip.md new file mode 100644 index 0000000..e69de29 diff --git a/docs/pack.md b/docs/pack.md new file mode 100644 index 0000000..52decbb --- /dev/null +++ b/docs/pack.md @@ -0,0 +1,67 @@ +# IPS 打包命令说明 + + +* [IPS 打包命令说明](#ips-打包命令说明) + * [简介](#简介) + * [使用方法](#使用方法) + * [命令语法](#命令语法) + * [示例](#示例) + * [转存文件打包 IP 数据库](#转存文件打包-ip-数据库) + * [转换 IP 数据库文件格式](#转换-ip-数据库文件格式) + * [打包 IP 数据库并指定字段](#打包-ip-数据库并指定字段) + * [注意事项](#注意事项) + + +## 简介 + +`ips pack` 命令用于将 IP 数据库文件转换成另一种格式的数据库文件。这对于需要将数据库从一种格式转换为另一种格式以满足特定应用需求的用户尤其有用。 + +## 使用方法 + +通过 `ips pack` 命令，用户可以指定源数据库文件及其格式，并定义目标数据库文件及其格式，还可以指定要包含在内的字段。 + +## 命令语法 + +```shell +ips pack -i inputFile [--input-format format] -o outputFile [--output-format format] [flags] +``` + +- `-i, --input-file string`：指定输入 IP 数据库文件的路径。必填项。 +- `--input-format string`：指定输入 IP 数据库文件的格式。默认为自动检测。 +- `--input-option string`：数据库读取器指定选项。具体信息请查阅相关的数据库格式文档或获取专业支持。 +- `-o, --output-file string`：指定输出 IP 数据库文件的路径。必填项。 +- `--output-format string`：指定输出 IP 数据库文件的格式。未指定时，使用输出文件的扩展名自动检测。 +- `--output-option string`：数据库写入器指定选项。具体信息请查阅相关的数据库格式文档或获取专业支持。 +- `--lang string`：设置输出信息的语言。默认为 `zh-CN` (中文)。 +- `-f, --fields string`：指定从输入文件中获取的字段。默认为所有字段。参数详细解释请参考 [IPS 配置说明](./config.md#fields)。 +- `-r, --rewrite-files string`：指定需要载入的改写文件列表。参数详细解释请参考 [IPS 配置说明](./config.md#rewritefiles)。 + +## 示例 + +### 转存文件打包 IP 数据库 + +```shell +# 将 dump.txt 转换为 ipdb 格式 +ips pack -i dump.txt -o geoip.ipdb +``` + +### 转换 IP 数据库文件格式 + +```shell +# 将 GeoLite2-City.mmdb 数据库文件转换为 ipdb 格式 +ips pack -i GeoLite2-City.mmdb -o geoip.ipdb +``` + +### 打包 IP 数据库并指定字段 + +```shell +# 仅导出国家和城市字段，并将数据库转换为 ipdb 格式 +ips pack -i GeoLite2-City.mmdb -o geoip.ipdb --fields "country,city" +``` + +## 注意事项 +- 在指定 `--input-file` 时，确保输入文件的路径正确，并且该文件存在。 +- 在指定 `--output-file` 时，确保输出文件的路径可访问，并且有足够的权限进行写入操作。 +- 使用 `--fields` 可以自定义输出文件中包含的数据字段，减少不必要的数据存储。 +- `--lang` 选项允许用户为输出数据设置特定的语言，适用于多语言支持的数据库。 +- 通过 `--rewrite-files` 可以应用自定义的数据改写规则，这在调整输出文件的数据内容时非常有用。 \ No newline at end of file diff --git a/docs/pack_en.md b/docs/pack_en.md new file mode 100644 index 0000000..9def108 --- /dev/null +++ b/docs/pack_en.md @@ -0,0 +1,68 @@ +# IPS Pack Command Documentation + + +* [IPS Pack Command Documentation](#ips-pack-command-documentation) + * [Introduction](#introduction) + * [Usage](#usage) + * [Command Syntax](#command-syntax) + * [Examples](#examples) + * [Dump File Packaging IP Database](#dump-file-packaging-ip-database) + * [Convert IP Database File Format](#convert-ip-database-file-format) + * [Package IP Database and Specify Fields](#package-ip-database-and-specify-fields) + * [Notes](#notes) + + +## Introduction + +The `ips pack` command is used to convert an IP database file into another format. This is particularly useful for users who need to convert the database from one format to another to meet specific application requirements. + +## Usage + +With the `ips pack` command, users can specify the source database file and its format, and define the target database file and its format, as well as specify the fields to be included. + +## Command Syntax + +```shell +ips pack -i inputFile [--input-format format] -o outputFile [--output-format format] [flags] +``` + +- `-i, --input-file string`：Specifies the path to the input IP database file. required. +- `--input-format string`：Specifies the format of the input IP database file. The default is auto-detection. +- `--input-option string`：Specifies options for the database reader. For more information, please consult the relevant database format documentation or obtain professional support. +- `-o, --output-file string`：Specifies the path to the output IP database file. required. +- `--output-format string`：Specifies the format of the output IP database file. If not specified, the format is auto-detected based on the output file extension. +- `--output-option string`：Specifies options for the database writer. For more information, please consult the relevant database format documentation or obtain professional support. +- `--lang string`：Sets the language of the output information. The default is zh-CN (Chinese). +- `-f, --fields string`：Specifies the fields to be extracted from the input file. The default is all fields. For a detailed explanation of the parameters, please refer to [IPS Configuration Documentation](./config_en.md#fields)。 +- `-r, --rewrite-files string`：Specifies a list of rewrite files to be loaded. For a detailed explanation of the parameters, please refer to [IPS Configuration Documentation](./config_en.md#rewritefiles)。 + +## Examples + +### Dump File Packaging IP Database + +```shell +# Convert dump.txt to ipdb format +ips pack -i dump.txt -o geoip.ipdb +``` + +### Convert IP Database File Format + +```shell +# Convert GeoLite2-City.mmdb database file to ipdb format +ips pack -i GeoLite2-City.mmdb -o geoip.ipdb +``` + +### Package IP Database and Specify Fields + +```shell +# Only export the country and city fields and convert the database to ipdb format +ips pack -i GeoLite2-City.mmdb -o geoip.ipdb --fields "country,city" +``` + +## Notes + +- When specifying `--input-file`, ensure the path to the input file is correct and that the file exists. +- When specifying `--output-file`, ensure the path to the output file is accessible and that you have sufficient permissions to write to it. +- Using `--fields` allows you to customize the data fields included in the output file, reducing unnecessary data storage. +- The `--lang` option allows users to set a specific language for the output data, suitable for databases with multilingual support. +- Custom data rewrite rules can be applied with `--rewrite-files`, which is very useful when adjusting the content of the output file. \ No newline at end of file diff --git a/docs/query.md b/docs/query.md new file mode 100644 index 0000000..4ca152e --- /dev/null +++ b/docs/query.md @@ -0,0 +1,93 @@ +# IPS 查询命令说明 + + +* [IPS 查询命令说明](#ips-查询命令说明) + * [简介](#简介) + * [使用方法](#使用方法) + * [命令语法](#命令语法) + * [示例](#示例) + * [命令行查询 IP 地址](#命令行查询-ip-地址) + * [管道查询 IP 地址](#管道查询-ip-地址) + * [自定义查询字段和输出格式](#自定义查询字段和输出格式) + * [注意事项](#注意事项) + + +## 简介 + +`ips` 命令不仅是 IPS 命令行工具的主入口，提供了多种子命令来处理 IP 数据库相关的操作，而且它本身也是查询命令，提供了查询 IP 地址的地理位置信息功能。 + +查询命令支持通过命令行参数或管道方式进行查询，适用于 IPv4 和 IPv6 地址，并且能够根据用户的配置输出自定义字段信息，以满足个性化的信息展示需求。 + + +## 使用方法 + +作为命令行工具，`ips` 提供了直观的命令行参数查询和灵活的管道查询两种方式，让用户可以快速查询 IP 地址的地理位置信息。 + +用户还可以自定义查询结果中包含的字段，以及输出格式和语言，以便获得最适合自己需求的信息展示。 + +## 命令语法 + +```shell +# 命令行参数查询 +ips [flags] + +# 管道查询 +echo | ips [flags] +``` + +- `-i, --file string`：同时指定 IPv4 和 IPv6 数据库文件的路径。 +- `--format string`：指定 IPv4 和 IPv6 数据库文件的格式，需要与 `--file` 配合使用。默认为自动检测。 +- `--database-option string`：数据库读取器指定选项。具体信息请查阅相关的数据库格式文档或获取专业支持。 +- `--ipv4-file string`：指定 IPv4 数据库文件的路径。 +- `--ipv4-format string`：指定 IPv4 数据库文件的格式，需要与 `--ipv4-file` 配合使用。默认为自动检测。 +- `--ipv6-file string`：指定 IPv6 数据库文件的路径。 +- `--ipv6-format string`：指定 IPv6 数据库文件的格式，需要与 `--ipv6-file` 配合使用。默认为自动检测。 +- `--text-format string`：指定文本输出的格式，支持 %origin 和 %values 参数。 +- `--text-values-sep string`：指定文本输出中值的分隔符，默认为空格。 +- `-j, --json bool`：以 JSON 格式输出结果。 +- `--json-indent bool`：以带缩进的 JSON 格式输出结果。参数详细解释请参考 [IPS 配置说明](./config.md#jsonindent)。 +- `--use-db-fields bool`：使用数据库中的字段名称。一般与 JSON 输出格式配合使用。参数详细解释请参考 [IPS 配置说明](./config.md#usedbfields)。 +- `--lang string`：设置输出信息的语言。默认为 `zh-CN` (中文)。参数详细解释请参考 [IPS 配置说明](./config.md#lang)。 +- `-f, --fields string`：指定从输入文件中获取的字段。默认为所有字段。参数详细解释请参考 [IPS 配置说明](./config.md#fields)。 +- `-r, --rewrite-files string`：指定需要载入的改写文件列表。参数详细解释请参考 [IPS 配置说明](./config.md#rewritefiles)。 +- `--loglevel string`：设置日志级别，全局参数，可选值为 `trace`、`debug`、`info`、`warn`、`error`、`fatal` 和 `panic`，默认值为 `info`。 + +## 示例 + +### 命令行查询 IP 地址 + +```shell +# 查询 IP 地址的地理位置信息 +ips 8.8.8.8 + +# 查询多个 IP 地址的地理位置信息 +ips 8.8.8.8 119.29.29.29 +``` + +### 管道查询 IP 地址 + +```shell +# 使用 echo 传递 IP 地址给 ips 命令 +echo 8.8.8.8 | ips + +# 与 cat / dig 等命令配合使用 +dig +short google.com | ips +``` + +### 自定义查询字段和输出格式 + +```shell +# 查询 IP 地址，仅输出国家和城市字段 +ips 8.8.8.8 -f "country,city" + +# 自定义文本输出格式 +ips 8.8.8.8 --text-format "%values" --text-values-sep ":" --fields "country,city" +``` + +## 注意事项 + +- 若初次使用，且没有指定数据库文件路径，则会自动下载 IP 数据库文件。 +- 关于默认 IP 数据库的选择 + - IPv4 的默认数据库为 `qqwry.dat`，选择纯真是因为目前有持续更新的社区资源（感谢 [@metowolf](https://github.com/metowolf)），对于非国内用户，建议使用 `GeoLite2-City.mmdb` 或商用数据库。 + - IPv6 的默认数据库为 `zxipv6wry.db`，由于数据库文件较小，可以初次使用 IPS 工具时的体验，但这个数据库内容较为陈旧（最后更新时间为 2021 年 7 月），建议使用 `GeoLite2-City.mmdb` 或商用数据库。 +- 部分国家 IP 地理位置信息更新较快，如果商业项目使用本工具，请务必更换为较新的商业数据库！ diff --git a/docs/query_en.md b/docs/query_en.md new file mode 100644 index 0000000..dd2f32e --- /dev/null +++ b/docs/query_en.md @@ -0,0 +1,93 @@ +# IPS Command Documentation + + +* [IPS Command Documentation](#ips-command-documentation) + * [Introduction](#introduction) + * [Usage](#usage) + * [Command Syntax](#command-syntax) + * [Examples](#examples) + * [Command-Line Query for IP Address](#command-line-query-for-ip-address) + * [Pipeline Query for IP Address](#pipeline-query-for-ip-address) + * [Customize Query Fields and Output Format](#customize-query-fields-and-output-format) + * [Notes](#notes) + + +## Introduction + +The `ips` command serves not only as the main entry point to the IPS command-line tool, offering a variety of sub-commands for managing IP database operations but also functions as a query command, providing the capability to retrieve geolocation information for IP addresses. + +The query command supports both command-line parameter and pipeline methods for queries, suitable for both IPv4 and IPv6 addresses. It can output custom field information based on user configuration, meeting the demand for personalized information display. + +## Usage + +As a command-line tool, `ips` offers intuitive command-line parameter queries and flexible pipeline queries, enabling users to swiftly obtain geolocation information for IP addresses. + +Users can also customize the fields included in the query results, as well as the output format and language, to obtain the display that best suits their needs. + +## Command Syntax + +```shell +# Command-line parameter query +ips [flags] + +# Pipeline query +echo | ips [flags] +``` + +- `-i, --file string`：Specifies the path to both IPv4 and IPv6 database files. +- `--format string`：Specifies the format for both IPv4 and IPv6 database files; used in conjunction with `--file`. The default is auto-detection. +- `--database-option string`：Specifies options for the database reader. For more information, consult the documentation for the relevant database format or seek professional support. +- `--ipv4-file string`：Specifies the path to the IPv4 database file. +- `--ipv4-format string`：Specifies the format for the IPv4 database file; used in conjunction with `--ipv4-file`. The default is auto-detection. +- `--ipv6-file string`：Specifies the path to the IPv6 database file. +- `--ipv6-format string`：Specifies the format for the IPv6 database file; used in conjunction with `--ipv6-file`. The default is auto-detection. +- `--text-format string`：Specifies the format for text output, supporting `%origin` and `%values` parameters. +- `--text-values-sep string`：Specifies the separator for values in text output, with the default being a space. +- `-j, --json bool`：Outputs results in JSON format. +- `--json-indent bool`：Outputs results in indented JSON format. For more details, refer to [IPS Configuration Documentation](./config_en.md#jsonindent)。 +- `--use-db-fields bool`：Uses field names as they appear in the database, typically used with JSON output. For more details, refer to [IPS Configuration Documentation](./config_en.md#usedbfields)。 +- `--lang string`：Sets the language for the output. The default is `zh-CN` (Chinese). For more details, refer to [IPS Configuration Documentation](./config_en.md#lang)。 +- `-f, --fields string`：Specifies the fields to retrieve from the input file. The default is all fields. For more details, refer to [IPS Configuration Documentation](./config_en.md#fields)。 +- `-r, --rewrite-files string`：Specifies a list of files to be rewritten based on the provided configurations. For more details, refer to [IPS Configuration Documentation](./config_en.md#rewritefiles)。 +- `--loglevel string`：Sets the logging level, a global parameter with possible values of `trace`, `debug`, `info`, `warn`, `error`, `fatal`, and `panic`, with the default being `info`. + +## Examples + +### Command-Line Query for IP Address + +```shell +# Query geolocation information for an IP address +ips 8.8.8.8 + +# Query geolocation information for multiple IP addresses +ips 8.8.8.8 119.29.29.29 +``` + +### Pipeline Query for IP Address + +```shell +# Use echo to pass the IP address to the ips command +echo 8.8.8.8 | ips + +# Use in combination with commands like cat or dig +dig +short google.com | ips +``` + +### Customize Query Fields and Output Format + +```shell +# Query an IP address, outputting only the country and city fields +ips 8.8.8.8 -f "country,city" + +# Customize text output format +ips 8.8.8.8 --text-format "%values" --text-values-sep ":" --fields "country,city" +``` + +## Notes + +- If used for the first time without specifying a database file path, the IP database file will be downloaded automatically. +- Regarding the default IP database selection: + - The default IPv4 database is `qqwry.dat`. The QQWry database is chosen due to its continuous updates from the community (thanks to [@metowolf](https://github.com/metowolf)). For international users, it is recommended to use `GeoLite2-City.mmdb` or a commercial database. + - The default IPv6 database is `zxipv6wry.db`. Its smaller size can offer a better initial experience when first using the IPS tool, but the database content is relatively outdated (last updated in July 2021). It is recommended to use `GeoLite2-City.mmdb` or a commercial database. +- The IP geolocation information for some countries is updated frequently. If this tool is used for commercial projects, it is essential to replace it with a more recent commercial database! + diff --git a/docs/server.md b/docs/server.md new file mode 100644 index 0000000..620759c --- /dev/null +++ b/docs/server.md @@ -0,0 +1,110 @@ +# IPS 服务命令说明 + + +* [IPS 服务命令说明](#ips-服务命令说明) + * [简介](#简介) + * [使用方法](#使用方法) + * [命令语法](#命令语法) + * [示例](#示例) + * [启动 IP 查询服务](#启动-ip-查询服务) + * [使用自定义数据库文件](#使用自定义数据库文件) + * [设置输出字段和语言](#设置输出字段和语言) + * [API 接口](#api-接口) + * [查询 IP 地址](#查询-ip-地址) + * [解析文本并查询信息](#解析文本并查询信息) + * [注意事项](#注意事项) + + +## 简介 + +`ips server` 命令用于启动一个 IPS 服务，该服务能够提供 IP 地址查询服务。 + +## 使用方法 + +使用 `ips server` 命令可以快速启动一个 IP 查询服务，它将监听指定的地址和端口。用户可以通过 HTTP 请求来查询 IP 地址，得到 JSON 格式的响应。 + +## 命令语法 + +```shell +ips server [--addr address] [flags] +``` + +- `-a, --addr string`：服务监听地址。默认值为 `0.0.0.0:6860`，表示在所有网络接口的 `6860` 端口上监听。 +- `-i, --file string`：同时指定 IPv4 和 IPv6 数据库文件的路径。 +- `--format string`：指定 IPv4 和 IPv6 数据库文件的格式，需要与 `--file` 配合使用。默认为自动检测。 +- `--database-option string`：数据库读取器指定选项。具体信息请查阅相关的数据库格式文档或获取专业支持。 +- `--ipv4-file string`：指定 IPv4 数据库文件的路径。 +- `--ipv4-format string`：指定 IPv4 数据库文件的格式，需要与 `--ipv4-file` 配合使用。默认为自动检测。 +- `--ipv6-file string`：指定 IPv6 数据库文件的路径。 +- `--ipv6-format string`：指定 IPv6 数据库文件的格式，需要与 `--ipv6-file` 配合使用。默认为自动检测。 +- `--lang string`：设置输出信息的语言。默认为 `zh-CN` (中文)。参数详细解释请参考 [IPS 配置说明](./config.md#lang)。 +- `-f, --fields string`：指定从输入文件中获取的字段。默认为所有字段。参数详细解释请参考 [IPS 配置说明](./config.md#fields)。 +- `-r, --rewrite-files string`：指定需要载入的改写文件列表。参数详细解释请参考 [IPS 配置说明](./config.md#rewritefiles)。 + +## 示例 + +### 启动 IP 查询服务 + +```shell +# 在本地 8080 端口启动服务 +ips server -a 127.0.0.1:8080 +``` + +### 使用自定义数据库文件 + +```shell +# 使用自定义数据库文件启动服务 +ips server -i GeoLite2-City.mmdb +``` + +### 设置输出字段和语言 + +```shell +# 启动服务，并设置输出字段和语言 +ips server -f "country,city" --lang en +``` + +## API 接口 + +### 查询 IP 地址 + +```http request +GET /api/v1/ip?ip= +Host: +Authorization: + +200 OK +{ + "ip": , // IP 地址 + "net": , // IP 地址所在子网，CIDR 格式 + "data": {} // 地理位置信息 +} + +400 InvalidArgs +``` + +### 解析文本并查询信息 + +```http request +GET /api/v1/query?text= +Host: +Authorization: + +200 OK +{ + "items": [ // 数据列表 + { + "ip": , // IP 地址 + "net": , // IP 地址所在子网，CIDR 格式 + "data": {} // 地理位置信息 + } + ] +} + +400 InvalidArgs +``` + +## 注意事项 + +- IPS 服务在默认入口(例如 `http://localhost:6860/` )提供了一个简单的 Web 页面，提供文本查询和结果展示功能，用作 Demo 演示。 +- IPS 服务暂未提供鉴权机制，请避免直接将服务暴露在公网环境下运行。 \ No newline at end of file diff --git a/docs/server_en.md b/docs/server_en.md new file mode 100644 index 0000000..1852074 --- /dev/null +++ b/docs/server_en.md @@ -0,0 +1,95 @@ +# IPS Server Command Documentation + +## Introduction + +The `ips server` command is used to launch an IPS server that can provide IP address query services. + +## Usage + +Using the `ips server` command, you can quickly start an IP query server that will listen on a specified address and port. Users can make HTTP requests to query IP addresses and receive responses in JSON format. + +## Command Syntax + +```shell +ips server [--addr address] [flags] +``` + +- `-a, --addr string`：Server listening address. Default is `0.0.0.0:6860`, which means listening on port 6860 on all network interfaces. +- `-i, --file string`：Specifies the path to both IPv4 and IPv6 database files. +- `--format string`：Specifies the format for both IPv4 and IPv6 database files; used in conjunction with `--file`. The default is auto-detection. +- `--database-option string`：Specifies options for the database reader. For more information, consult the documentation for the relevant database format or seek professional support. +- `--ipv4-file string`：Specifies the path to the IPv4 database file. +- `--ipv4-format string`：Specifies the format for the IPv4 database file; used in conjunction with `--ipv4-file`. The default is auto-detection. +- `--ipv6-file string`：Specifies the path to the IPv6 database file. +- `--ipv6-format string`：Specifies the format for the IPv6 database file; used in conjunction with `--ipv6-file`. The default is auto-detection. +- `--lang string`：Sets the language for the output. The default is `zh-CN` (Chinese). For more details, refer to [IPS Configuration Documentation](./config_en.md#lang)。 +- `-f, --fields string`：Specifies the fields to retrieve from the input file. The default is all fields. For more details, refer to [IPS Configuration Documentation](./config_en.md#fields)。 +- `-r, --rewrite-files string`：Specifies a list of files to be rewritten based on the provided configurations. For more details, refer to [IPS Configuration Documentation](./config_en.md#rewritefiles)。 + +## Examples + +### Start an IP Query Server + +```shell +# Start the server on local port 8080 +ips server -a 127.0.0.1:8080 +``` + +### Use a Custom Database File + +```shell +# Start the server using a custom database file +ips server -i GeoLite2-City.mmdb +``` + +### Set Output Fields and Language + +```shell +# Start the server and set output fields and language +ips server -f "country,city" --lang en +``` + +## API Interface + +### Query IP Address + +```http request +GET /api/v1/ip?ip= +Host: +Authorization: + +200 OK +{ + "ip": , // IP address + "net": , // Subnet of the IP address, in CIDR format + "data": {} // Geolocation information +} + +400 InvalidArgs +``` + +### Parse Text and Query Information + +```http request +GET /api/v1/query?text= +Host: +Authorization: + +200 OK +{ + "items": [ // List of data + { + "ip": , // IP address + "net": , // Subnet of the IP address, in CIDR format + "data": {} // Geolocation information + } + ] +} + +400 InvalidArgs +``` + +## Notes + +- The IPS server provides a simple web page at the default entry point (e.g., `http://localhost:6860/` ) for text queries and result display, serving as a demo presentation. +- The IPS server does not currently provide an authentication mechanism, so please avoid exposing the service directly on the public internet. diff --git a/docs/usage.md b/docs/usage.md new file mode 100644 index 0000000..1011824 --- /dev/null +++ b/docs/usage.md @@ -0,0 +1,22 @@ +# IPS 使用指南 + +欢迎使用 IPS！这是一个命令行工具与库，旨在帮助您轻松完成 IP 地理位置数据库的查询、转存与打包。 + +## 详细命令和配置 + +- [IPS 配置说明](./config.md) - 介绍 IPS 的配置参数和配置文件。 +- [IPS 下载命令说明](./download.md) - 下载 IP 地理位置数据库。 +- [IPS 转存命令说明](./dump.md) - 转存 IP 地理位置数据库。 +- [IPS 打包命令说明](./pack.md) - 打包 IP 地理位置数据库。 +- [IPS 查询命令说明](./query.md) - 查询 IP 地理位置。 +- [IPS 服务命令说明](./server.md) - 启动 IPS 服务。 + +## 支持的数据库格式 + +IPS 支持多种数据库格式。更多关于每种格式的信息，请查阅以下链接： +- [IPDB 格式数据库](./format_ipdb.md) + +## 高级用法 + +探索 IPS 的高级用法，包括裁减字段和自定义数据库操作，请参考 [高级用法示例](./advanced_usage.md)。 + diff --git a/docs/usage_en.md b/docs/usage_en.md new file mode 100644 index 0000000..f7552b0 --- /dev/null +++ b/docs/usage_en.md @@ -0,0 +1,22 @@ +# IPS Usage Guide + +Welcome to IPS! This is a command-line tool and library designed to help you easily query, dump, and package IP geolocation databases. + +## Detailed Commands and Configuration + +- [IPS Configuration Documentation](./config_en.md) - Introduces the configuration parameters and configuration file for IPS. +- [IPS Download Command Documentation](./download_en.md) - Download IP geolocation databases. +- [IPS Dump Command Documentation](./dump_en.md) - Dump IP geolocation databases. +- [IPS Pack Command Documentation](./pack_en.md) - Package IP geolocation databases. +- [IPS Command Documentation](./query_en.md) - Query IP geolocation information. +- [IPS Server Command Documentation](./server_en.md) - Start the IPS service. + +## Supported Database Formats + +IPS supports multiple database formats. For more information about each format, please refer to the following link: + +- [IPDB Database Format](./format_ipdb_en.md) + +## Advanced Usage + +Explore the advanced uses of IPS, including trimming fields and custom database operations, please refer to [Advanced Usage Examples](./advanced_usage_en.md). \ No newline at end of file diff --git a/internal/ips/config.go b/internal/ips/config.go index f6383dc..81ce877 100644 --- a/internal/ips/config.go +++ b/internal/ips/config.go @@ -110,7 +110,7 @@ type Config struct { // MyIPCount defines the minimum number of detectors that should return the same IP // for the IP to be considered as the system's public IP. - MyIPCount int `mapstructure:"my_ip_count" default:"3"` + MyIPCount int `mapstructure:"myip_count" default:"3"` // MyIPTimeoutS specifies the maximum duration (in seconds) to wait for the detectors to return an IP. MyIPTimeoutS int `mapstructure:"myip_timeout_s"`