diff --git a/docs/about_us/contributor.en.md b/docs/about_us/contributor.en.md new file mode 100644 index 000000000..e7715db57 --- /dev/null +++ b/docs/about_us/contributor.en.md @@ -0,0 +1,38 @@ +# Contributor List + +!!! tip "Thank you to all friends who have contributed to JumpServer. The world is different because of you." + +!!! tip "" + - **[Lao Guang ][ibuler]** JumpServer Founder + - **[Halcyon ][halcyon]** Senior DevOps Developer, JumpServer's second developer + - **[Jiaxiangkong ][jiaxiangkong]** JumpServer Test Operations + - **[Liuz ][liuz]** Full-stack Engineer, wrote most of the Web Terminal code + - **[Yumaojun03 ][yumaojun03]** Senior DevOps Developer, proficient in Python, Go, and PaaS platform development + - **[Kelianchun ][kelianchun]** Senior DevOps Developer, fixed many bugs + - **[Xiaoyu
  • ][小彧]** Senior Django Developer, contributed many codes for the user module, provided assistance during difficult times for JumpServer + - **[Sofia ][sofia]** Senior Frontend Engineer, frontend code contributor + - **[Q4speed ][q4speed]** Architect, Guacamole integration contributor, made significant contributions for Windows support + - **[Liqiang-fit2cloud ][liqiang-fit2cloud]** Version testing, provided many suggestions for asset tree design + - **[Wojiushixiaobai ][wojiushixiaobai]** Improved documentation, tested bugs, enthusiastically helped many friends + - **[Qiuser ][Qiuser]** Tested bugs, enthusiastically helped many friends + - **[Xiaobai ][BaiJiangJie]** Core developer from v1.0 to present + - **[LeeEirc
  • ][LeeEirc]** Senior Development Engineer, proficient in Go platform development, developer of KoKo component + - **[Orange ][Orange]** Core developer, responsible for JumpServer frontend work + - **[Baqianliu ][八千流]** Core tester (auxiliary developer), responsible for JumpServer testing + +[ibuler]: https://github.com/ibuler +[halcyon]: https://github.com/halcyon +[jiaxiangkong]: https://github.com/jiaxiangkong +[liuz]: https://github.com/liuz +[yumaojun03]: https://github.com/yumaojun03 +[kelianchun]: https://github.com/kelianchun +[小彧]: https://github.com/xkong +[sofia]: https://github.com/sofia +[q4speed]: https://github.com/q4speed +[liqiang-fit2cloud]: https://github.com/liqiang-fit2cloud +[wojiushixiaobai]: https://github.com/wojiushixiaobai +[Qiuser]: https://github.com/qiuDar +[LeeEirc]: https://github.com/LeeEirc +[Orange]: https://github.com/orangemio +[八千流]: https://github.com/jym503558564 +[BaiJiangJie]: https://github.com/BaiJiangJie diff --git a/docs/architecture.en.md b/docs/architecture.en.md new file mode 100644 index 000000000..124133f34 --- /dev/null +++ b/docs/architecture.en.md @@ -0,0 +1,24 @@ +# System Architecture +## 1 Application Architecture +!!! tip "" + - JumpServer adopts a layered architecture consisting of load layer, access layer, core layer, data layer, and storage layer. + - The JumpServer application architecture diagram is as follows: +![architecture_01](img/architecture_01.png) + +## 2 Component description +!!! tip "" + - The Core component is the core component of JumpServer, and other components depend on it to start. + - Koko is the component for Unix-like asset platforms, providing character connections through SSH and Telnet protocols. + - Lion is the component for Windows asset platforms, used to access Windows assets from the Web. + - XRDP is the component for RDP protocol, primarily used to access Windows assets such as Windows 2000, XP systems through JumpServer Client. + - Razor is the component for RDP protocol; JumpServer Client uses the Razor component by default to access Windows assets. + - Magnus is the component for databases, used to access database assets through client proxy. + - Kael is the component for GPT asset platforms, used to manage ChatGPT assets. + - Chen is the component for databases, used to access database assets through Web GUI. + - Celery is the component for handling asynchronous tasks, used to execute JumpServer-related automation tasks. + - Video is specifically for processing the format conversion of session recordings produced by Razor and Lion components, converting generated session recordings to MP4 format. + - Panda is an application publisher based on domestic operating systems, used to schedule Virtualapp applications. + + +## 3 Logical architecture +!!! tip "See [Source Code Deployment](installation/source_install/requirements.md) for details" diff --git a/docs/best_practices.en.md b/docs/best_practices.en.md new file mode 100644 index 000000000..844488651 --- /dev/null +++ b/docs/best_practices.en.md @@ -0,0 +1,16 @@ +# Best Practices + +!!! tip "" + - [JumpServer user permission system usage practices](https://kb.fit2cloud.com/?p=170){:target="_blank"} + - [JumpServer master-backup deployment recording synchronization](https://kb.fit2cloud.com/?p=132){:target="_blank"} + - [Temporary solution for JumpServer extra-long recording playback anomalies](https://kb.fit2cloud.com/?p=131){:target="_blank"} + - [JumpServer integration with Syslog log system](https://kb.fit2cloud.com/?p=123){:target="_blank"} + - [How to enhance JumpServer user login security](https://kb.fit2cloud.com/?p=71){:target="_blank"} + - [JumpServer custom user role permissions](https://kb.fit2cloud.com/?p=42){:target="_blank"} + - [Common JumpServer MFA tools](https://kb.fit2cloud.com/?p=6){:target="_blank"} + - [Implement bastion machine remote Linux (Ubuntu) desktop through open source XRDP](https://kb.fit2cloud.com/?p=140){:target="_blank"} + - [How to resolve slow asset connection queries in different regions?](https://kb.fit2cloud.com/?p=138){:target="_blank"} + - [Razor component untrusted certificate causes asset connection failure](https://kb.fit2cloud.com/?p=116){:target="_blank"} + - [VSCode connecting to JumpServer assets](https://kb.fit2cloud.com/?p=48){:target="_blank"} + - [Session sharing && multi-user collaborative operations](https://kb.fit2cloud.com/?p=41){:target="_blank"} + - [Different passwords for the same system user on different assets](https://kb.fit2cloud.com/?p=19){:target="_blank"} diff --git a/docs/change_log.en.md b/docs/change_log.en.md new file mode 100644 index 000000000..ef5d875b7 --- /dev/null +++ b/docs/change_log.en.md @@ -0,0 +1,183 @@ +# Changelog + +v4.10.15 +------------------------ +January 22, 2026 + +!!! info "New Features 🌱" + - feat: Added API Rate Limiting mechanism to enhance interface call stability and security + - feat: Quick filter capability added to ticket list for improved ticket query and processing efficiency (JumpServer EE) + +!!! summary "Feature Optimization 🚀" + - perf: Upgraded Lion component base image to 1.5.5-trixie + - perf: Windows asset account password change now supports password verification through pyfreerdp (JumpServer EE) + +!!! success "Bug Fixes 🐛" + - fix: Fixed authentication service not properly validating certificates + - fix: Fixed issue where corresponding sub-account switching was not created when creating accounts through account templates + + +v4.10.14 +------------------------ +December 18, 2025 + +!!! info "New Features 🌱" + - feat: JumpServer Client now supports OAuth 2.0 authentication method for improved client login compatibility + - feat: Virtual applications support VNC protocol connections through local clients (JumpServer EE) + +!!! summary "Feature Optimization 🚀" + - perf: Smart Q&A feature supports custom model configuration to meet different intelligent interaction scenarios + - perf: Kubernetes platform protocol adds namespace configuration support; users can only access authorized namespaces when connecting for enhanced access control precision + +!!! success "Bug Fixes 🐛" + - fix: Fixed memory leak issue in Razor component (JumpServer EE) + - fix: Fixed issue where session sharing links could not be copied when connecting through different endpoints + + +v4.10.13 +------------------------ +November 20, 2025 + +!!! info "New Features 🌱" + - feat: Brand new JumpServer client with smaller size and better user experience (V4) + - feat: PostgreSQL backend database now supports SSL encrypted connections + +!!! summary "Feature Optimization 🚀" + - perf: All component base images upgraded to Debian 13 (trixie) + - perf: Supports batch import of weak password lists + + +v4.10.12 +------------------------ +October 27, 2025 + +!!! summary "Feature Optimization 🚀" + - perf: Optimized password usage mechanism and user permission validation in LDAP service connection testing + - perf: Optimized user query logic in KoKo session sharing; returns maximum 10 results by default + + +v4.10.11 +------------------------ +October 21, 2025 + +!!! success "Bug Fixes 🐛" + - fix: Optimized permission verification logic when obtaining SuperConnectionToken + + +v4.10.10 +------------------------ +October 16, 2025 + +!!! info "New Features 🌱" + - feat: Added data masking feature【Enterprise Edition】Chen and KoKo support all relational databases + - feat: Magnus only supports MySQL databases + +!!! summary "Feature Optimization 🚀" + - perf: Optimized Razor asset connection stuttering and high memory usage issues (upgraded to FreeRDP3) 【Enterprise Edition】 + - perf: Account push interface adds user group gid parameter + +!!! success "Bug Fixes 🐛" + - fix: Fixed inaccurate display of ACLs rules when selecting all assets in global organizations【Enterprise Edition】 + + +v4.10.9 +------------------------ +September 24, 2025 + +!!! summary "Feature Optimization 🚀" + - perf: Lion file management supports uploading multiple files simultaneously + +!!! success "Bug Fixes 🐛" + - fix: Fixed high memory usage issue in KoKo + + +v4.10.8 +------------------------ +September 18, 2025 + +!!! info "New Features 🌱" + - feat: Added global resource search feature + - feat: Supports displaying announcements in popups + +!!! summary "Feature Optimization 🚀" + - perf: Improved cloud sync to avoid releasing assets【Enterprise Edition】 + - perf: Improved RDP true color (24-bit) display + +!!! success "Bug Fixes 🐛" + - fix: Fixed issue where access keys remain valid after user expiration + - fix: Fixed Chen complex SQL query export failure + +v4.10.7 +------------------------ +September 4, 2025 + +!!! summary "Feature Optimization 🚀" + - perf: Encrypted storage of key fields in AccessKey table (migration completed) + +!!! success "Bug Fixes 🐛" + - fix: Fixed user MFA reset failure + +v4.10.6 +------------------------ +August 29, 2025 + +!!! success "Bug Fixes 🐛" + - fix: Resolved all components going offline after upgrade + - fix: Fixed Nec component freezing when using password-only authentication to connect to RealVNC server + +v4.10.5 +------------------------ +August 22, 2025 + +!!! info "New Features 🌱" + - feat: Added reporting feature to support visual data analysis and export【Enterprise Edition】 + - feat: Added character search in KoKo to accelerate information finding + +!!! summary "Feature Optimization 🚀" + - perf: User AccessKey stored in encrypted form to improve security + - perf: Disable Passkey as MFA when SAFE_MODE is enabled for enhanced security + +v4.10.4 +------------------------ +July 16, 2025 + +!!! summary "Feature Optimization 🚀" + - perf: Cloud sync tasks now support switching automatic host information updates【Enterprise Edition】 + +v4.10.3 +------------------------ +July 1, 2025 + +!!! success "Bug Fixes 🐛" + - fix: Fixed command record count showing 0 after configuring Elasticsearch for command storage + - fix: Fixed KoKo session showing WebSocket disconnect warning + +v4.10.2 +------------------------ +June 20, 2025 + +!!! info "New Features 🌱" + - feat: Support users to set personal language preference + - feat: Quick commands in Adhoc will hide account name hints when SAFE_MODE=true is enabled + +!!! success "Bug Fixes 🐛" + - fix: Fixed remote application publishing failure + - fix: Fixed asset type tree nested display anomaly + +v4.10.1 +------------------------ +May 19, 2025 + +!!! success "Bug Fixes 🐛" + - fix: Fixed client download failure + - fix: Fixed watermark enable exception in community edition + +v4.10.0 +------------------------ +May 15, 2025 + +!!! success "Major Update ⚡️" + + - feat: Multi-language support: including English, Chinese (Simplified), Chinese (Traditional), Japanese, Portuguese (Brazil), Spanish, Russian, and Korean + +!!! info "New Features 🌱" diff --git a/docs/contact.en.md b/docs/contact.en.md new file mode 100644 index 000000000..3a3f2c9ba --- /dev/null +++ b/docs/contact.en.md @@ -0,0 +1,36 @@ +# Contact Us + +## 1 GitHub Project Address +!!! tip "" + - [JumpServer][jumpserver] ![jumpserver stars][jumpserver stars] + +## 2 Contact information +!!! tip "" + - Official website: https://www.jumpserver.org/ + - Email: support@fit2cloud.com + - Phone: 400-052-0755 + - Community forum: [Open source community forum][Open source community forum] + - Enterprise edition trial application: https://jumpserver.org/enterprise.html + - Technical consultation: https://jinshuju.net/f/sQ91MK + +## 3 WeChat Official Account +![wechat-official](img/wechat-official.png){ width="156px" } + +## 4 WeChat Group +![wechat-group](img/weixin_group.png){ width="156px" } + +## 5 Smart Customer Service +![evo-bot](img/AI_helper.png){ width="156px" } + +## 6 Learning Certification +![contact01](img/contact01.png){ width="156px" } + +## 7 Online Documentation Feedback +!!! tip "" + - If you find any issues while reading this documentation, we welcome your feedback through the following form, and we will optimize it as soon as possible. + - [Online documentation feedback form][Online documentation feedback form] + +[jumpserver]: https://github.com/jumpserver/jumpserver +[jumpserver stars]: https://img.shields.io/github/stars/jumpserver/jumpserver.svg +[Online documentation feedback form]: https://doc.weixin.qq.com/forms/AFYAQAeUAAwAHIANQZoAP0vuxVj1HRR3f +[Open source community forum]: https://bbs.fit2cloud.com/c/js/5 diff --git a/docs/dev/rest_api.en.md b/docs/dev/rest_api.en.md new file mode 100644 index 000000000..0a100bc26 --- /dev/null +++ b/docs/dev/rest_api.en.md @@ -0,0 +1,136 @@ +# API Documentation + +!!! info "Note" + API documentation is integrated into the code by default. After deployment is complete, you can access it using the following methods: + +## 1 API Access +!!! tip "" + + | Version | Access Method | Example | + | ------------------------ | ------------------------ | ---------------------------------- | + | `{{ jumpserver.tag }}` | `http:///api/docs/` | `http://192.168.244.144/api/docs/` | + +### 1.1 Page Effect +![api_swagger](../img/api_swagger.png) + +## 2 API Authentication + +!!! tip "JumpServer API supports the following authentication methods:" + ``` + Session Can directly use session_id as authentication method after login + Token Get a one-time Token with expiration time. Token becomes invalid after expiration. + Private Token Permanent Token + Access Key Sign Http Header + ``` + + === "Session" + After logging in through the page, jms_sessionid will exist in cookies. Include jms_sessionid in cookies when making requests. + + === "Token" + ```sh + curl -X POST http://localhost/api/v1/authentication/auth/ \ + -H 'Content-Type: application/json' \ + -d '{"username": "admin", "password": "admin"}' + ``` + === "Python" + ```python + import requests + import json + + url = 'http://localhost/api/v1/authentication/auth/' + data = { + 'username': 'admin', + 'password': 'admin' + } + + response = requests.post(url, json=data) + token = response.json()['token'] + print(token) + ``` + + === "Golang" + ```go + package main + + import ( + "bytes" + "encoding/json" + "fmt" + "io/ioutil" + "net/http" + ) + + func main() { + url := "http://localhost/api/v1/authentication/auth/" + data := map[string]string{ + "username": "admin", + "password": "admin", + } + + jsonData, _ := json.Marshal(data) + response, _ := http.Post(url, "application/json", bytes.NewBuffer(jsonData)) + + body, _ := ioutil.ReadAll(response.Body) + result := make(map[string]interface{}) + json.Unmarshal(body, &result) + + fmt.Println(result["token"]) + } + ``` + === "Java" + ```java + import java.io.InputStream; + import java.io.OutputStream; + import java.net.HttpURLConnection; + import java.net.URL; + + public class JumpServerAPI { + public static void main(String[] args) throws Exception { + String url = "http://localhost/api/v1/authentication/auth/"; + String params = "{\"username\": \"admin\", \"password\": \"admin\"}"; + + URL obj = new URL(url); + HttpURLConnection connection = (HttpURLConnection) obj.openConnection(); + + connection.setRequestMethod("POST"); + connection.setRequestProperty("Content-Type", "application/json"); + + connection.setDoOutput(true); + OutputStream os = connection.getOutputStream(); + os.write(params.getBytes()); + os.flush(); + + InputStream is = connection.getInputStream(); + byte[] buffer = new byte[1024]; + int len; + StringBuilder response = new StringBuilder(); + while ((len = is.read(buffer)) != -1) { + response.append(new String(buffer, 0, len)); + } + + System.out.println(response.toString()); + } + } + ``` + + === "Private Token" + ```sh + docker exec -it jms_core /bin/bash + cd /opt/jumpserver/apps + python manage.py shell + from users.models import User + u = User.objects.get(username='admin') + u.create_private_token() + ``` + If a private_token already exists, you can get it directly: + ```python + u.private_token + ``` + For example, with PrivateToken: 937b38011acf499eb474e2fecb424ab3: + ```sh + curl -H 'Authorization: PrivateToken 937b38011acf499eb474e2fecb424ab3' \ + http://localhost/api/v1/users/users/ + ``` + + === "Access Key" + Create or get AccessKeyID and AccessKeySecret in the API Key list on the Web page. diff --git a/docs/dev/shell.en.md b/docs/dev/shell.en.md new file mode 100644 index 000000000..53940c28e --- /dev/null +++ b/docs/dev/shell.en.md @@ -0,0 +1,109 @@ +# Interactive Commands + +!!! warning "Improper operation will result in data loss. Please confirm carefully before operating." + +## 1 Operation Method + +!!! tip "" + ```sh + docker exec -it jms_core bash + cd /opt/jumpserver/apps + python manage.py shell + ``` + ```python + # Starting from the new version, you need to switch to the corresponding organization before operating. Default is 'Default' + from orgs.models import * + Organization.objects.all() + org = Organization.objects.get(name='Default') + org.change_to() + ``` + +!!! tip "" + - Select the interactive command object to view + + === "User" + ```python + from users.models import * + + # User + User.objects.all() + User.objects.count() # Count + + # Query specific user + user = User.objects.get(username = 'admin') + + # Query user email + user.email + + # Modify user email + user.email='test@jumpserver.org' + + # Change password + user.reset_password('test01') + + # Save modifications + user.save() + + # Delete user MFA key + user.otp_secret_key='' + user.save() + + # Create new user + User.objects.create(name = 'Test User', username = 'test', email = 'test@jumpserver.org') + + # Test if user exists, create if not + User.objects.get_or_create(name = 'Test User', username = 'test', email = 'test@jumpserver.org') + + user = User.objects.get(username = 'test') + user.delete() + + # More elegant deletion method + User.objects.all().filter(username='test').delete() + ``` + ```python + # User groups + UserGroup.objects.all() + UserGroup.objects.count() + + # Create user group + UserGroup.objects.create(name = 'Test') + ``` + + === "Asset" + ```python + from assets.models import * + + # Asset + Asset.objects.all() + Asset.objects.count() + + # Query asset by name + asset = Asset.objects.get(name='asset_name') + + # Modify asset + asset.address='192.168.1.100' + asset.save() + + # Delete asset + asset.delete() + ``` + + +## 2 Data Decryption +!!! tip "" + + === "System User" + ```sh + docker exec -it jms_core python manage.py shell + from assets.models import SystemUser + su = SystemUser.objects.all().first() + print(su.password) + ``` + + === "System Settings Fields" + ```sh + docker exec -it jms_core python manage.py shell + from settings.models import Setting + setting = Setting.objects.get(name='EMAIL_PASSWORD') + print(setting.value) + ``` diff --git a/docs/faq/enterprise.en.md b/docs/faq/enterprise.en.md new file mode 100644 index 000000000..113db6172 --- /dev/null +++ b/docs/faq/enterprise.en.md @@ -0,0 +1,21 @@ +# Enterprise Edition + +## 1 What are the Differences Between JumpServer Open Source and Enterprise Editions? +!!! tip "" + **JumpServer's core features are all open source, releasing new versions monthly, and are permanently free to use.** + + Compared to JumpServer's open source edition, JumpServer's enterprise edition provides an X-Pack enhancement package for enterprise-level application scenarios and high-level factory-level enterprise support services. It also provides JumpServer operations and security best practices to effectively assist enterprises in rapidly building and operating their own operations and security audit systems. + + The X-Pack enhancement package includes additional features required by enterprise customers, such as custom page logos, multi-organization management, and support for managing Oracle and PostgreSQL databases. The specific features of the X-Pack enhancement package will continue to increase with each new version release. + +!!! tip "" + - [JumpServer Enterprise Edition Feature List](https://www.jumpserver.org/enterprise.html) + +!!! info "X-Pack enhancement package features will continue to be added monthly with JumpServer version iterations. Enterprise customers do not need to pay additional fees to use newly added features during their service period." + + +## 2 How to Apply for Enterprise Edition? How is Enterprise Edition Priced? +!!! tip "" + JumpServer Enterprise Edition trial application: https://jinshuju.net/f/kyOYpi + + We will arrange a specialist to contact you. diff --git a/docs/faq/faq.en.md b/docs/faq/faq.en.md new file mode 100644 index 000000000..b491e5f64 --- /dev/null +++ b/docs/faq/faq.en.md @@ -0,0 +1,43 @@ +# Product FAQ +## 1 Common Issues Summary +!!! tip "" + - [JumpServer Common Issues Summary](https://kb.fit2cloud.com/?p=73) + - [JumpServer Query Logs Method](https://kb.fit2cloud.com/?p=8b420906-c41e-417a-b171-8414213d8f8e) + - [JumpServer Component Related Common Issues](https://kb.fit2cloud.com/?p=288bcfe2-c7f6-4954-984c-55c115b524e9) + +## 2 System Management Related +!!! tip "" + - [Linux Common High-Risk Commands Summary](https://kb.fit2cloud.com/?p=173) + - [JumpServer Storage Directory Migration](https://kb.fit2cloud.com/?p=d2555b92-6992-4c8d-9282-20ed06f10add) + - [How to Use Your Own SSL Certificate to Access JumpServer?](https://kb.fit2cloud.com/?p=152) + - [JumpServer Login Password Forgotten and User Lock Handling](https://kb.fit2cloud.com/?p=53) + - [JumpServer Connecting Elasticsearch Cluster Storage Commands](https://kb.fit2cloud.com/?p=220) + - [How to Get "Connectable" and "Hardware Information" in Asset List?](https://kb.fit2cloud.com/?p=216) + - [How to Modify the Waiting Time After JumpServer Connects to Other Authentication Methods?](https://kb.fit2cloud.com/?p=213) + - [How to Limit a Specific Asset to Only Allow Login to JumpServer from Certain IPs Before Connection?](https://kb.fit2cloud.com/?p=199) + - [How to Connect JumpServer to Windows AD Domain?](https://kb.fit2cloud.com/?p=167) + - [How to Resolve Network Segment Conflicts Between Managed Assets and JumpServer Backend Docker Networks?](https://kb.fit2cloud.com/?p=163) + +## 3 Feature Module Related +!!! tip "" + - [V3 Version Remote Application Publishing and Usage](https://kb.fit2cloud.com/?p=9beffa46-3b58-456b-9db0-7a0b2a9cc665) + - [How to Use Different Users for Access Control?](https://kb.fit2cloud.com/?p=0edf37d8-4834-4e8f-8cd2-0ea0c07de1b2) + - [Linux Assets Inventory & Login Connection Common Errors & File Upload Download](https://kb.fit2cloud.com/?p=86) + +## 4 Identity Authentication Related +!!! tip "" + - [JumpServer Connection to LDAP Identity Authentication](../manual/admin/system_settings/authentication_settings/LDAP.md) + - [JumpServer Connection to OAuth2 Authentication](../manual/admin/system_settings/authentication_settings/OAuth2.md) + - [JumpServer Connection to OIDC Authentication](../manual/admin/system_settings/authentication_settings/OIDC.md) + - [JumpServer Connection to SAML2 Authentication](../manual/admin/system_settings/authentication_settings/SAML2.md) + - [JumpServer Connection to Radius Authentication](../manual/admin/system_settings/authentication_settings/Radius.md) + + +## 5 Version Related +!!! tip "" + - [JumpServer V3 Version Interpretation](https://mp.weixin.qq.com/s/ofN6KUyjabaWw4HVdvLQ8Q) + +## 6 Upgrade Related +!!! tip "" + - [JumpServer Upgrade Issues](https://kb.fit2cloud.com/?p=9aaf5bc6-7071-4be0-96fd-98295feee3f2) + - [JumpServer Upgrade Rollback Instructions](https://kb.fit2cloud.com/?p=4ba65333-bf41-42f7-b329-afc855e7789a) diff --git a/docs/faq/security.en.md b/docs/faq/security.en.md new file mode 100644 index 000000000..729f819b3 --- /dev/null +++ b/docs/faq/security.en.md @@ -0,0 +1,29 @@ +# Security Recommendations + +## 1 Basic Security Requirements +!!! tip "" + - JumpServer needs to open at least ports 80, 443, and 2222 to the outside. + - The operating system of the server where JumpServer is located should be upgraded to the latest version. + - The software that JumpServer depends on should be upgraded to the latest version. + - Servers, databases, Redis and other dependent components should not use weak password credentials. + - It is not recommended to disable Firewalld and SELinux. + - Only open necessary ports. If necessary, access JumpServer through VPN or SSL VPN. + - If you must open to the external network, you should deploy a Web Application Firewall for security filtering. + - Deploy SSL certificates and access JumpServer through HTTPS protocol. + - JumpServer should set strong password rules in security settings and prohibit users from using weak passwords. + - Should enable JumpServer MFA authentication to prevent security issues caused by password leaks. + +!!! warning "Note" + - If JumpServer security issues are discovered, please report to us at ibuler@fit2cloud.com + +## 2 Security Configuration Recommendations +!!! tip "" + - [Linux Common High-Risk Commands Summary](https://kb.fit2cloud.com/?p=173){:target="_blank"} + - [Limit a Specific Asset to Only Allow Login to JumpServer from Certain IPs](https://kb.fit2cloud.com/?p=199){:target="_blank"} + - [Use Your Own SSL Certificate to Access JumpServer](https://kb.fit2cloud.com/?p=152){:target="_blank"} + - [Enhance User Login Security in JumpServer](https://kb.fit2cloud.com/?p=71){:target="_blank"} + - [User Account Switching on JumpServer Login](https://kb.fit2cloud.com/?p=65){:target="_blank"} + - [JumpServer High-Risk Command Restrictions](https://kb.fit2cloud.com/?p=63){:target="_blank"} + - [Limit Source IP Login to JumpServer Bastion Host](https://kb.fit2cloud.com/?p=43){:target="_blank"} + - [JumpServer Commonly Used MFA Tools](https://kb.fit2cloud.com/?p=6){:target="_blank"} + - [Set JumpServer Session Expiration Time](https://kb.fit2cloud.com/?p=5){:target="_blank"} diff --git a/docs/index.en.md b/docs/index.en.md new file mode 100644 index 000000000..9efe107c9 --- /dev/null +++ b/docs/index.en.md @@ -0,0 +1,94 @@ +# Product Introduction + +??? warning "Important Notice | JumpServer Vulnerability Notification and Fix 2025-10-30 (CVE-2025-62712|CVE-2025-62795)" + **In October 2025, users reported security vulnerabilities in JumpServer open source bastion machine and reported them to the JumpServer open source project team.** + + **Vulnerability Information：** +
    1. [JumpServer token list for connected sessions has privilege escalation risk, CVE number CVE-2025-62712](https://nvd.nist.gov/vuln/detail/CVE-2025-62712) +
    2. [JumpServer LDAP configuration has unauthorized testing risk, CVE number CVE-2025-62795](https://nvd.nist.gov/vuln/detail/CVE-2025-62795) + + **Affected versions:**
    JumpServer V3: <=v3.10.20 LTS +
    JumpServer V4: <=v4.10.11 LTS + + **Secure versions:**
    JumpServer V3: >=v3.10.21 LTS +
    JumpServer V4: >=v4.10.12 LTS + + **Fix solutions:** +
    **Permanent fix:** Upgrade JumpServer software to the above secure versions. +
    **Temporary fix:** Restrict access to relevant API endpoints with minimal impact to main JumpServer functions. **Nginx configuration example:** + + ```nginx + # CVE-2025-62712 + location /api/v1/authentication/super-connection-token/ { + return 200 ''; + } + location /api/v1/resources/super-connection-tokens/ { + return 200 ''; + } + + # CVE-2025-62795, this will disable test and import functions in ldap config + location /ws/ldap { + return 200 ''; + } + + ``` + **Special thanks to:**
    Thanks to SolidLab for discovering and timely reporting the above vulnerabilities to the JumpServer open source community. + + +## 1 What is JumpServer? +!!! tip "" + JumpServer is a popular open source bastion machine that is a professional operation and maintenance security audit system conforming to the 4A specification. JumpServer helps enterprises manage and log in to all types of assets in a more secure way, implementing pre-authorization, in-process monitoring, and post-audit to meet compliance requirements. + +![index_02](https://www.jumpserver.com/images/jumpserver-arch-light.png) + +!!! tip "" + JumpServer bastion machine supports the following asset types: + + - SSH (Linux / Unix / Network devices, etc.) + - Windows (Web access / native RDP access) + - Database (MySQL / MariaDB / Oracle / SQL Server / PostgreSQL / ClickHouse, etc.) + - NoSQL (Redis / MongoDB, etc.) + - GPT (ChatGPT, etc.) + - Cloud services (Kubernetes / VMware vSphere, etc.) + - Web sites (Web management backends of various systems) + - Applications (various applications accessed through Remote App) + +!!! tip "Documentation Guide" + + [**Official Website**](https://jumpserver.org/)       [**Installation and Deployment**](installation/setup_linux_standalone/requirements/)       [**Online Demo**](https://demo.jumpserver.org/ )       [**Enterprise Edition Trial**](https://jinshuju.net/f/kyOYpi)       [**Community Forum**](https://bbs.fit2cloud.com/c/js/5)       [**Video Teaching**](https://www.bilibili.com/video/BV11AsDegEo8/)       [**Technical Whitepaper**](https://whitepaper.jumpserver.org/) + +## 2 Product Features +!!! tip "" + JumpServer product features include: + + - Open source: Zero threshold, quickly obtain and install online + - Distributed: Easily support large-scale concurrent access + - Plugin-free: Browser only, ultimate Web Terminal experience + - Multi-cloud support: One system managing assets across different clouds + - Cloud storage: Audit recordings stored in cloud, never lost + - Multi-tenant: One system for multiple subsidiaries and departments + - Multi-application support: Database, Windows remote applications, Kubernetes + +## 3 Page Display +![!Interface Display](img/dashboard.png) + +## 4 Application Store +!!! tip "" + JumpServer's remote application feature supports Chrome and DBeaver applications by default in community edition, and supports richer remote applications in enterprise edition. Click [Application Store](https://apps.fit2cloud.com/jumpserver) to get more remote applications. + +## 5 Security Statement +!!! tip "" + - JumpServer is a security product. Please follow [basic security recommendations](faq/security.md) for installation and deployment. + - If you discover security issues, please contact us directly: support@fit2cloud.com + +## 6 Commercial Products +!!! tip "" + - [JumpServer Enterprise Edition](https://jumpserver.org/enterprise.html){:target="_blank"} + - [JumpServer Appliance](https://jumpserver.org/hardware.html){:target="_blank"} + +## 7 Learn More +!!! tip "" + - [How to introduce JumpServer to your team?](https://www.fit2cloud.com/jumpserver/documents/introduce-jumpserver_202511.pdf) + - [JumpServer Technical Whitepaper](https://whitepaper.jumpserver.org/){:target="_blank"} + - [JumpServer Knowledge Base](https://kb.fit2cloud.com/categories/jumpserver){:target="_blank"} + - [Teaching Videos](https://space.bilibili.com/510493147?spm_id_from=333.337.0.0){:target="_blank"} diff --git a/docs/installation/1panel_setup/config_js.en.md b/docs/installation/1panel_setup/config_js.en.md new file mode 100644 index 000000000..4f1b9bdae --- /dev/null +++ b/docs/installation/1panel_setup/config_js.en.md @@ -0,0 +1,54 @@ +# Configure JumpServer on 1Panel + +## 1 SSL/TLS Certificate Configuration +!!! warning "Note" + - First, ensure that the openresty application is already installed and deployed in 1Panel. +!!! tip "" + - Open 1Panel, in the left navigation bar click **Website** → **Certificates** → **Upload Certificate** button to access the **Upload Certificate** module. Users can configure the certificate's private key and certificate information through two methods: paste code or select file from server. + +![img](../../img/V4_1panel_config1.png) +!!! tip "" + You can also create certificates through applying for certificates or self-signed certificates. + The system will automatically identify domain names, certificate issuer organization and other information based on the submitted private key and certificate files. +![img](../../img/V4_1panel_config2.png) +!!! tip "" + - The following is based on OpenResty. In the left navigation bar, click **Website** → **Website** → **Create Website**, select **JumpServer** from installed applications, configure related domain information, and enable **HTTPS** at the bottom. Click **Confirm** button to complete website creation. + +## 2 Modify Configuration File +!!! tip "" + - Find **Containers** in the left menu, click **Containers** at the top to view specific containers. Find the image corresponding to **jms_all** and click **More** in the **Operation** column on the right, then click **Edit**. +![img](../../img/V4_1panel_config3.png) +!!! tip "" + - On the edit page, scroll down to the bottom, select the **Labels & Environment Variables** section, and access the file configuration area. +![img](../../img/V4_1panel_config4.png) +!!! tip "" + - Scroll down to the **Environment Variables** section. You can modify, add, and delete environment variable content. Click **Confirm** after modification to complete configuration file updates. + +## 3 Upgrade Operation +!!! tip "" + - First, in the 1panel Linux operations panel left navigation bar, click **Containers**. Then in the right top navigation bar, click **Containers** button to view all containers currently managed by the server. +![img](../../img/V4_1panel_config5.png) +!!! tip "" + - Find the jms_all container (JumpServer service provider), in the right operation buttons, click **More** → **Upgrade**, select an appropriate new version image from the target image, and finally click **Confirm** button to complete JumpServer upgrade. +![img](../../img/V4_1panel_config6.png) +## 4 View Logs +!!! tip "" + - Containers → Find the jumpserver container → Operation → View container logs. + +## 5 Application Backup +### 5.1 Enter Application Management +!!! tip "" + - Log in to the 1Panel console. + - In the left menu, select **App Store** → **Installed**. + - Find the JumpServer application, click the **Backup** button on the right. + +### 5.2 Perform Backup Operation +!!! tip "" + - On the backup page, find the **Backup** button. + - You can enter compress or decompress passwords (if any) and description for the backup (if any). + - Click confirm to automatically complete the backup operation. + +### 5.3 Restore Backup Content +!!! tip "" + - Click backup at the top right, select the backup file you need to restore. + - Click **Restore** to return to the state when the backup was made. diff --git a/docs/installation/1panel_setup/setup_js.en.md b/docs/installation/1panel_setup/setup_js.en.md new file mode 100644 index 000000000..6645eb22e --- /dev/null +++ b/docs/installation/1panel_setup/setup_js.en.md @@ -0,0 +1,47 @@ +# Deploy JumpServer with 1Panel + +## 1. Install 1Panel +!!! tip "" + - For 1Panel installation, deployment and basic feature introduction, please refer to [1Panel Official Documentation](https://1panel.cn/docs/v2/installation/online_installation/). + - After completing the 1Panel installation and deployment, open your browser and access 1Panel according to the provided URL. + + +## 2. Install Database and Redis Service +!!! warning "" + - Before installing JumpServer, you need to install the required **PostgreSQL** (or **MySQL**) and **Redis** applications in 1Panel first. + +## 3. Install JumpServer +!!! tip "" + - Open the App Store menu, search for **JumpServer** in the search bar, and click **Install** after finding it. + +![img](../../img/V4_1Panel_setup1.png) +!!! tip "" + - Before installation, various installation version information and database selection information will be displayed. Enter the database password and other information, then click **Confirm** to start the installation. + +![img](../../img/V4_1panel_setup2.png) + +!!! tip "Detailed parameter description:" + + | Parameter | Description | + | ------------------- | ------------------------------------------------------------ | + | Name | The name of the JumpServer application to be created. | + | Version | The version of the JumpServer application to be created. | + | Encryption Signature | JumpServer's SECRET_KEY. Keep default. Save this SECRET_KEY for migration environments. | + | Authentication Token | JumpServer's BOOTSTRAP_TOKEN. Keep default. Save this BOOTSTRAP_TOKEN for migration environments. | + | Debug Mode | Support enabling debug mode. | + | Log Level | Log level. Support DEBUG, INFO, WARNING, ERROR, CRITICAL levels. | + | Database Service | The PostgreSQL database application used by JumpServer. You can select from already installed PostgreSQL applications. 1Panel will automatically configure JumpServer to use this database. | + | Database Name | The database name used by JumpServer. 1Panel will automatically create this database in the selected database. | + | Edit compose file | Support customizing the compose file to start containers. | + + + +!!! info "If the following log records appear, **TASK-END** indicates installation is complete." + +![img](../../img/V4_1panel_setup4.png) + +## 4. Access JumpServer +!!! info "After successful installation, access JumpServer through your browser." + ```sh + http://your_server_ip:port + ``` diff --git a/docs/installation/backup_recovery.en.md b/docs/installation/backup_recovery.en.md new file mode 100644 index 000000000..964e83d52 --- /dev/null +++ b/docs/installation/backup_recovery.en.md @@ -0,0 +1,64 @@ +# Data Backup and Recovery + +## 1 Overview + +!!! tip "" + **JumpServer bastion host data is mainly divided into two parts:** + + - Database data: User data, asset data, account data, operation logs, command records, etc. + - Static files: Session recordings, images, system logs, configuration files, etc. + +## 2 Database Backup and Recovery + +!!! warning "Note" + - This document takes backup and recovery in the same environment as an example. For cross-environment recovery, ensure database version and type are consistent. The **BOOTSTRAP_TOKEN** and **SECRET_KEY** in the configuration file must be the same as the export source! + +!!! tip "" + === "Backup" + - Execute the following command on any node of the bastion host to backup database information: + ```bash + jmsctl backup_db + ``` + - If MySQL or MariaDB is used as the database, the file name format is jumpserver-v4.10.9-xxxx-xx-xx_xx:xx:xx.sql. + + === "Restore" + - Execute the following command on any node of the bastion host to restore database information: + ```bash + jmsctl restore_db /path/to/backup.sql + ``` + +## 3 Static File Backup + +!!! warning "Note" + - Static files mainly include session recordings, images, system logs, etc. Static files are saved in /data/jumpserver by default. If static file paths are custom, backup and recovery should be done according to the actual paths. + - For cross-environment recovery, ensure database data and static file data sources are consistent, otherwise recordings and other data cannot be associated. + - For multi-node environments, it is recommended to use shared storage solutions such as NFS to avoid inconsistency in static files on single nodes. + +!!! tip "" + - Static file directory structure: + ```sh + ├── core + │ └── data + │ ├── celery + │ ├── certs + │ ├── logs # System logs + │ ├── media # Session recordings, etc. + │ ├── share + │ ├── static + │ ├── system + │ └── version.txt + ├── db_backup # Backed up database files and configuration files + ├── koko + │ └── data + │ ├── certs + │ ├── keys # Component registration information + │ ├── logs # koko component logs, similar for other components + │ └── replays + ├── nginx + │ └── data + │ └── logs # Nginx access logs (jms_web) + ├── redis + │ └── data + └── postgresql + └── data + ``` diff --git a/docs/installation/download.en.md b/docs/installation/download.en.md new file mode 100644 index 000000000..3714956ef --- /dev/null +++ b/docs/installation/download.en.md @@ -0,0 +1,22 @@ +# Resource Download + +## [VideoPlayer](https://github.com/jumpserver/VideoPlayer/releases){:target="_blank"} + +!!! tip "" + - JumpServer offline recording player can be downloaded and installed from the JumpServer page's `Help Menu` - `Tools Download`. + - Supports playing recordings saved in multiple formats. + +## [Clients](https://github.com/jumpserver/clients/releases){:target="_blank"} + +!!! tip "" + - JumpServer client is integrated by default into the JumpServer image and can be downloaded and installed from the JumpServer page's `Help Menu` - `Tools Download`. The open-source version supports local launching of SSH, while the enterprise version also supports RDP launching. + +## [Jmservisor](https://github.com/jumpserver/Jmservisor/releases){:target="_blank"} + +!!! tip "" + - JumpServer RemoteApp client for launching Windows Server RemoteApp functionality. Users can download and install from the JumpServer page's `Help Menu` - `Tools Download`. + +## [Installer](https://community.fit2cloud.com/#/products/jumpserver/downloads){:target="_blank"} + +!!! tip "" + - JumpServer installer is available for download. Follow the installation guide for your platform. diff --git a/docs/installation/jmsctl_sh.en.md b/docs/installation/jmsctl_sh.en.md new file mode 100644 index 000000000..821b274ad --- /dev/null +++ b/docs/installation/jmsctl_sh.en.md @@ -0,0 +1,51 @@ +# Command-line Tools + +## 1 Command-line Operations Tool - jmsctl + +!!! tip "" + - JumpServer includes a built-in command-line operations tool - jmsctl. Execute the `jmsctl help` command to view relevant help documentation. + + ```sh + JumpServer Deployment Management Script + + Usage: + ./jmsctl.sh [COMMAND] [ARGS...] + ./jmsctl.sh --help + + Installation Commands: + install Install JumpServer service + + Management Commands: + config Configuration tool; execute jmsctl config --help to view help + start Start JumpServer service + stop Stop JumpServer service + restart Restart JumpServer service + status View JumpServer service running status + down Take JumpServer service offline + uninstall Uninstall JumpServer service + + More Commands: + load_image Load Docker image + backup_db Backup JumpServer database + restore_db [file] Restore data through database backup file + raw Execute raw docker compose command + tail [service] View Service logs + ``` + +## 2 Configuration Tool - jmsctl config + +!!! tip "" + - JumpServer includes a built-in configuration tool - jmsctl config. Execute the `jmsctl config help` command to view relevant help documentation. + + ```sh + Usage: + ./jmsctl.sh config [ARGS...] + -h, --help + + Args: + ntp Configure NTP synchronization + init Initialize config configuration file + port Configure JumpServer service port + ssl Configure Web SSL + env Configure JumpServer environment variables + ``` diff --git a/docs/installation/migration.en.md b/docs/installation/migration.en.md new file mode 100644 index 000000000..2049cccb9 --- /dev/null +++ b/docs/installation/migration.en.md @@ -0,0 +1,75 @@ +# Migration Guide + +!!! warning "Note" + - Maintain SECRET_KEY consistent with the old version during upgrade and migration, otherwise encrypted data in the database cannot be decrypted. + +## 1 Migration Instructions + +!!! tip "v2.6 Version Upgrade Instructions" + - Unified installation method for enterprise and open-source versions; community version can seamlessly switch to enterprise version. + - Only this installation method will be maintained going forward; other installation methods will no longer provide technical support. + - After installation, configuration file is in /opt/jumpserver/config/config.txt + +## 2 Migration Steps + +### 2.1 Database Backup + +!!! tip "" + - Get database information from the jumpserver/config.txt file: + + ```yaml + DB_HOST: 127.0.0.1 # Database server IP + DB_PORT: 3306 # Database server port + DB_USER: jumpserver # User for database connection + DB_PASSWORD: ****** # Password for database connection user + DB_NAME: jumpserver # Database used by JumpServer + # mysqldump -h -P -u -p > /opt/.sql + ``` + +!!! tip "" + - Select the database backup method corresponding to your environment deployment: + + === "installer deployment" + ```bash + jmsctl backup_db + ``` + + === "source code deployment" + ```bash + mysqldump -h -P -u -p > /opt/.sql + ``` + + === "containerized component deployment" + ```bash + docker exec jms_db_1 /usr/bin/mysqldump -uroot -pjumpserver jumpserver > /opt/jumpserver.sql + ``` + +### 2.2 Modify Database Character Set + +!!! tip "" + - If you don't need or don't want to handle database character set, skip this step. Just ensure the database character set is the same before and after migration. + ```bash + ALTER DATABASE jumpserver CHARACTER SET utf8 COLLATE utf8_general_ci; + ``` + +### 2.3 Download jumpserver-install + +!!! tip "" + ```bash + cd /opt + wget https://github.com/jumpserver/jumpserver/releases/download/v4.10.9/jumpserver-installer-v4.10.9.tar.gz + tar xf jumpserver-installer-v4.10.9.tar.gz + cd jumpserver-installer-v4.10.9 + ``` + +### 2.4 Edit Temporary Configuration File + +!!! tip "" + ```bash + vi quick_start.sh + ``` + +## 2.5 Start JumpServer Deployment + +!!! tip "" + - Select the deployment method corresponding to your database environment. diff --git a/docs/installation/network_port.en.md b/docs/installation/network_port.en.md new file mode 100644 index 000000000..a679f8972 --- /dev/null +++ b/docs/installation/network_port.en.md @@ -0,0 +1,62 @@ +# Network Port Description + +## 1 Network Port List + +!!! tip "" + - JumpServer, as a professional operation and maintenance security audit system conforming to 4A standards, requires opening the following network ports for normal operation. Administrators can open relevant ports on the network and host sides according to the actual deployment scheme of JumpServer components in their environment. + +| Port | Function | Description | +| --- | --- | --- | +| 22 | SSH | Installation, upgrade, and management | +| 80 | Web HTTP Service | Access JumpServer frontend page via HTTP protocol | +| 443 | Web HTTPS Service | Access JumpServer frontend page via HTTPS protocol | +| 3306 | Database Service | MySQL service | +| 6379 | Database Service | Redis service | +| 3389 | Razor Service Port | RDP Client method to connect to Windows assets | +| 2222 | SSH Client | Use terminal tools like Xshell, PuTTY, MobaXterm to connect to JumpServer via SSH Client | +| 33061 | Magnus MySQL Service Port | DB Client method to connect to MySQL database assets | +| 33062 | Magnus MariaDB Service Port | DB Client method to connect to MariaDB database assets | +| 54320 | Magnus PostgreSQL Service Port | DB Client method to connect to PostgreSQL database assets | +| 63790 | Magnus Redis Service Port | DB Client method to connect to Redis database assets | +| 15210 | Magnus Oracle Service Port | DB Client method to connect to Oracle database assets | +| 15900 | NEC Service Port | VNC service | + +## 2 Firewall Common Commands + +!!! tip "" + - Confirm firewall status is running + ```bash + firewall-cmd --state + ``` + +!!! tip "" + - Temporarily open port (rule takes effect immediately, fails on reboot) + ```bash + firewall-cmd --zone=public --add-port=80/tcp --permanent + ``` + +!!! tip "" + - Temporarily close port (rule takes effect immediately, fails on reboot) + ```bash + firewall-cmd --zone=public --remove-port=80/tcp --permanent + ``` + +!!! tip "" + - Permanently allow port (requires reload to take effect) + ```bash + firewall-cmd --zone=public --add-port=80/tcp --permanent + firewall-cmd --reload + ``` + +!!! tip "" + - Permanently remove port (requires reload to take effect) + ```bash + firewall-cmd --zone=public --remove-port=80/tcp --permanent + firewall-cmd --reload + ``` + +!!! tip "" + - View effective port rules + ```bash + firewall-cmd --zone=public --list-all + ``` diff --git a/docs/installation/previous_version_upgrade/1.0.0-1.4.3.en.md b/docs/installation/previous_version_upgrade/1.0.0-1.4.3.en.md new file mode 100644 index 000000000..ba13da47e --- /dev/null +++ b/docs/installation/previous_version_upgrade/1.0.0-1.4.3.en.md @@ -0,0 +1,115 @@ +# Upgrade from Version 1.0.0-1.4.3 to 1.4.4 + +!!! warning "Note" + - Keep SECRET_KEY consistent with the old version during upgrade and migration, otherwise encrypted database data cannot be decrypted. + - Be sure to backup the database and JumpServer source code before updating. + +## 1 Backup Database +!!! tip "" + ```sh + cp -r /opt/jumpserver /opt/jumpserver_bak + mysqldump -uroot -p jumpserver > /opt/jumpserver.sql + ``` + +## 2 Upgrade Steps +!!! warning "Note: Please read each step carefully and understand it before proceeding with the upgrade" + - Check the current version of each component first. + - Upgrade from version 0.x to 1.x is not supported. + - Starting from version 1.4.x, MySQL version needs to be greater than or equal to 5.7 + - Update the configuration file by copying the old version settings to the new configuration file. + +### 2.1 Stop Core +!!! tip "" + ```sh + cd /opt/jumpserver + source /opt/py3/bin/activate + ./jms stop + ``` + +!!! tip "" + - Replace /opt with your actual installation directory. + +### 2.2 Switch to 1.4.4 Branch +!!! tip "" + ```sh + cd /opt/jumpserver + git fetch + git checkout 1.4.4 + git pull + ``` + +??? question "If executing git pull prompts an error, handle according to the prompt" + - Error: Your local changes to the following file would be overwritten by merge + + ```sh + git reset --hard + git pull + ``` + +??? tip "If your code is not obtained from the GitHub repository, use this hidden help for migration" + 1. Backup database + 2. Obtain new version code + 3. Copy old configuration files to new location + 4. Update dependencies + 5. Execute migration + 6. Start service + +### 2.3 Update Dependencies +!!! tip "" + ```sh + pip install -r requirements/requirements.txt + ``` + +??? question "Ensure Python3 virtual environment is loaded. If errors occur during installation, usually it's because dependency packages are not fully installed. Use search engines to solve" + - Domestically, you can use mirror acceleration. + + ```sh + pip install -i https://pypi.tuna.tsinghua.edu.cn/simple + ``` + +### 2.4 Handle Upgrade + +!!! tip "" + ```sh + cd utils + sh make_migrations.sh + ``` + +??? question "If executing sh make_migrations.sh has errors, refer here for handling" + - You have an error in your SQL syntax; check the manual than corresponds to your MySql server version for the right syntax to use near '(6) NOT NULL' + + ```sh + # Modify database charset + ALTER DATABASE jumpserver CHARACTER SET utf8 COLLATE utf8_general_ci; + ``` + +!!! warning "Note" + - Versions smaller than 1.1.0 need to execute this step before upgrading. + + ```sh + cd utils + sh 1.0.x_to_1.1.0_migrations.sql + ``` + +!!! warning "Note" + - Versions smaller than 1.4.0 need to execute this step before upgrading. + + ```sh + cd utils + sh 1.3.x_to_1.4.0_migrations.sql + ``` + +### 2.5 Start Core + +!!! tip "" + ```sh + cd /opt/jumpserver + source /opt/py3/bin/activate + ./jms start + ``` + +!!! tip "" + - Ensure there are no errors on startup. + +!!! tip "" + - Then upgrade according to the [1.4.4 to 1.4.5 upgrade](1.4.4.en.md) documentation, otherwise normal use will not be possible. diff --git a/docs/installation/previous_version_upgrade/1.4.4.en.md b/docs/installation/previous_version_upgrade/1.4.4.en.md new file mode 100644 index 000000000..e06bb99ac --- /dev/null +++ b/docs/installation/previous_version_upgrade/1.4.4.en.md @@ -0,0 +1,98 @@ +# Upgrade from Version 1.4.4 to 1.4.5 + +!!! warning "Note" + - Keep SECRET_KEY consistent with the old version during upgrade and migration, otherwise encrypted database data cannot be decrypted. + - Be sure to backup the database and JumpServer source code before updating. + +## 1 Backup Database +!!! tip "" + ```sh + cp -r /opt/jumpserver /opt/jumpserver_1.4.4_bak + mysqldump -uroot -p jumpserver > /opt/jumpserver_1.4.4.sql + ``` + +## 2 Upgrade Steps +!!! warning "Note: Please read carefully and understand each step before operating the upgrade" + - Check the current version of each component first. + - This document is only applicable to upgrading version 1.4.4. + - Starting from version 1.4.x, MySQL version needs to be greater than or equal to 5.7 + - Update the configuration file by copying the old version settings to the new configuration file. + +### 2.1 Stop Core +!!! tip "" + ```sh + cd /opt/jumpserver + source /opt/py3/bin/activate + ./jms stop + ``` + +!!! tip "" + - Replace /opt with your actual installation directory. + +### 2.2 Update Code + +!!! tip "" + ```sh + cd /opt/jumpserver + git fetch + git checkout 1.4.5 + git pull + ``` + +??? question "If executing git pull prompts an error, handle according to the prompt" + - Error: Your local changes to the following file would be overwritten by merge + + ```sh + git reset --hard + git pull + ``` + +### 2.3 Update Dependencies + +!!! tip "" + ```sh + pip install -r requirements/requirements.txt + ``` + +### 2.4 Handle Upgrade + +!!! tip "" + ```sh + cd utils + vi 1.4.4_to_1.4.5_migrations.sh + ``` + ```vim + #!/bin/bash + # + + # Modify database information to your jumpserver database. Can be found in config.py or config.yml + + host=127.0.0.1 # Modify to your database + port=3306 + username=root # Username + db=jumpserver # Database name + + echo "Backup original migrations" + mysqldump -u${username} -h${host} -P${port} -p ${db} django_migrations > django_migrations.sql.bak + ret=$? + + if [ ${ret} == "0" ];then + # Execute upgrade script + mysql -u${username} -h${host} -P${port} -p ${db} < 1.4.4_to_1.4.5_migrations.sql + fi + ``` + +### 2.5 Start Core + +!!! tip "" + ```sh + cd /opt/jumpserver + source /opt/py3/bin/activate + ./jms start + ``` + +!!! tip "" + - Ensure there are no errors on startup. + +!!! tip "" + - Then upgrade to the latest version according to the [upgrade documentation](../upgrade_notice.md), otherwise normal use will not be possible. diff --git a/docs/installation/previous_version_upgrade/mariadb-mysql.en.md b/docs/installation/previous_version_upgrade/mariadb-mysql.en.md new file mode 100644 index 000000000..915376f67 --- /dev/null +++ b/docs/installation/previous_version_upgrade/mariadb-mysql.en.md @@ -0,0 +1,140 @@ +# Database Migration +!!! warning "Note" + - Be sure to backup before migration. + - Starting from v2.5, MySQL >= 5.7 is required + - It is recommended to use external databases for convenient expansion and upgrade. + +## 1 Database Requirements +!!! tip "" + - Version requirements for MySQL/MariaDB and Redis are as follows: + +!!! tip "" + | DB | Version | Cache | Version | + | :------ | :------ | :---- | :------ | + | MySQL | >= 5.7 | Redis | >= 6.0 | + | MariaDB | >= 10.6 | - | - | + +## 2 Operation Process +!!! tip "Backup Database" + === "Manual Deployment" + ```sh + cp -r /opt/jumpserver /opt/jumpserver_bak + mysqldump -uroot -p jumpserver > /opt/jumpserver.sql + ``` + + === "Containerized Components" + ```sh + docker exec -it jms_db /bin/bash + cd /opt/jumpserver/data + mysqldump -uroot -p jumpserver > /opt/jumpserver.sql + ``` + + === "Using setuptools" + ```sh + cd /opt/jumpserver + ./jms backup_db + ``` + + === "Docker Deployment" + ```sh + docker exec jms_db /bin/bash -c 'mysqldump -uroot -ppassword jumpserver > /opt/jumpserver.sql' + docker cp jms_db:/opt/jumpserver.sql /opt/ + ``` + + === "Docker Compose" + ```sh + docker-compose exec -T db /bin/bash -c 'mysqldump -uroot -ppassword jumpserver > /opt/jumpserver.sql' + docker cp jms_db:/opt/jumpserver.sql /opt/ + ``` + === "JumpServer Installer" + ```sh + cd /opt/jumpserver-installer-version + ./jmsctl.sh backup_db + ``` + +!!! tip "Modify Database Character Set" + ```sh + if grep -q 'COLLATE=utf8_bin' /opt/jumpserver.sql; then + cp /opt/jumpserver.sql /opt/jumpserver_bak.sql + sed -i 's@COLLATE utf8_bin@@g' /opt/jumpserver.sql + else + echo "Database character set is correct"; + fi + ``` + +!!! tip "Migrate to New Server" + - Copy the exported /opt/jumpserver.sql to the new server. + - The following example takes migration to another CentOS7 server as an example. In actual operation, please replace the corresponding commands as needed. + + === "Migrate to MariaDB 10.6" + ```sh + # Install MariaDB + yum -y install mariadb-server + systemctl start mariadb + systemctl enable mariadb + + # Import database + mysql -uroot < /opt/jumpserver.sql + + # Verify import success + mysql -uroot -e 'use jumpserver; select * from users_user;' + ``` + + === "Migrate to MySQL 5.7" + ```sh + # Install MySQL 5.7 + yum -y install mysql-community-server + + # Start MySQL + systemctl start mysqld + systemctl enable mysqld + + # Import database + mysql -uroot -p < /opt/jumpserver.sql + + # Verify import success + mysql -uroot -p -e 'use jumpserver; select * from users_user;' + ``` + + === "Migrate to MySQL 8.0" + ```bash + # Install MySQL 8.0 + yum -y install mysql-community-server + + # Start MySQL + systemctl start mysqld + systemctl enable mysqld + + # Reset password + grep 'password' /var/log/mysqld.log + mysql -uroot -p + + # Import database + mysql -uroot -p < /opt/jumpserver.sql + + # Verify import success + mysql -uroot -p -e 'use jumpserver; select * from users_user;' + ``` + + === "Migrate to Docker Container" + ```sh + # Start database container + docker run -d --name jms_db -p 3306:3306 -e MYSQL_ROOT_PASSWORD=password mysql:5.7 + + # Import database + docker cp /opt/jumpserver.sql jms_db:/opt/ + docker exec -it jms_db bash + mysql -uroot -p < /opt/jumpserver.sql + exit + ``` + - Start jms_core and check jumpserver.log for errors. + +!!! question "Startup Error: Cannot add foreign key constraint" + ```sh + # Check database encoding + mysql -uroot -p + select @@collation_database, @@character_set_database; + + # Modify database encoding + ALTER DATABASE jumpserver CHARACTER SET utf8 COLLATE utf8_general_ci; + ``` diff --git a/docs/installation/proxy.en.md b/docs/installation/proxy.en.md new file mode 100644 index 000000000..8eda4cb86 --- /dev/null +++ b/docs/installation/proxy.en.md @@ -0,0 +1,73 @@ +# Reverse Proxy + +!!! info "JumpServer Reverse Proxy Requirements" + - RDP protocol copy/paste requires deploying trusted SSL certificates. + - Access via HTTPS protocol enables copy/paste functionality in RDP assets. + - Follow recommendations from [Mozilla SSL Configuration Generator](https://ssl-config.mozilla.org/){:target="_blank"}. + +## 1 Nginx SSL Deployment + +!!! tip "Prepare SSL certificates (note: certificates must be in pem format)" + - Place certificates in /opt/jumpserver/config/nginx/cert. + - Close JumpServer service before modifying configuration files. + +!!! tip "" + ```bash + # Close JumpServer service + ./jmsctl.sh stop + ``` + ```bash + # Edit JumpServer main configuration file + vi /opt/jumpserver/config/config.txt + ``` + ```vim + ... + + ## Nginx Configuration + HTTP_PORT=80 + SSH_PORT=2222 + RDP_PORT=3389 + + ## HTTPS Configuration + HTTPS_PORT=443 # External HTTPS port, default 443 + SSL_CERTIFICATE=/opt/jumpserver/config/nginx/cert/server.crt + SSL_CERTIFICATE_KEY=/opt/jumpserver/config/nginx/cert/server.key + ``` + +## 2 Multi-layer Nginx Reverse Proxy + +!!! tip "Note" + - Suitable for environments with unified external exit reverse proxy servers + - Each layer must set websocket long connection + +!!! tip "" + ```nginx + upstream jumpserver { + server jumpserver_ip:80; + } + + server { + listen 80; + server_name _; + client_max_body_size 5000m; + + location / { + proxy_pass http://jumpserver; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + } + ``` + +!!! tip "Recommend deploying SSL for more secure HTTPS protocol access" + - Follow [Mozilla SSL Configuration Generator](https://ssl-config.mozilla.org/) recommendations. + +## 3 Other SLB + +!!! tip "Note" + - Just need to pay attention to websocket long connection settings. + - Need to pay attention to session issues. diff --git a/docs/installation/security_setup/mysql_ssl.en.md b/docs/installation/security_setup/mysql_ssl.en.md new file mode 100644 index 000000000..8323b1004 --- /dev/null +++ b/docs/installation/security_setup/mysql_ssl.en.md @@ -0,0 +1,42 @@ +# Database SSL Connection + +## 1 Operation Process +### 1.1 Prepare Database CA File +!!! tip "" + - Prepare the database CA file. Currently, private key authentication is not supported. + + ```bash + mkdir -p /opt/jumpserver/config/certs + cp db_ca.pem /opt/jumpserver/config/certs/db_ca.pem + ``` + + - Test the MySQL connection without errors. + + ```bash + # . /opt/jumpserver/config/config.txt + # mysql --ssl-ca=/opt/jumpserver/config/certs/db_ca.pem -h$DB_HOST -P$DB_PORT -u$DB_USER -p$DB_PASSWORD $DB_NAME + ``` + +### 1.2 Edit Configuration File +!!! tip "" + - Open the configuration file. + + ```bash + vi /opt/jumpserver/config/config.txt + ``` + + - Configure DB SSL in the configuration file. + + ```vim + DB_USE_SSL=True + ``` + +### 1.3 Restart JumpServer Service +!!! tip "" + ```bash + cd /opt/jumpserver-installer-{{ jumpserver.tag }} + ./jmsctl.sh down + ./jmsctl.sh start + ``` + +!!! warning "For other JumpServer deployment methods, place the database certificate db_ca.pem in /opt/jumpserver/data/certs and restart" diff --git a/docs/installation/security_setup/redis_ssl.en.md b/docs/installation/security_setup/redis_ssl.en.md new file mode 100644 index 000000000..676c50825 --- /dev/null +++ b/docs/installation/security_setup/redis_ssl.en.md @@ -0,0 +1,65 @@ +# Redis SSL Connection + +## 1 Operation Process +### 1.1 Prepare Database CA File +=== "Method 1" + !!! tip "" + - Prepare the Redis CA file (cloud providers usually only provide the CA file) + + ```bash + mkdir -p /opt/jumpserver/config/certs/certs + cp redis_ca.crt /opt/jumpserver/config/certs/redis_ca.crt + ``` + + - Test the Redis connection without errors. + + ```bash + # . /opt/jumpserver/config/config.txt + # redis-cli --tls --cacert /opt/jumpserver/config/certs/redis_ca.crt -h $REDIS_HOST -p $REDIS_PORT -a $REDIS_PASSWORD info + ``` + +=== "Method 2" + !!! tip "" + - Prepare the Redis CA file, private key, and certificate (self-signed certificate) + + ```bash + mkdir -p /opt/jumpserver/config/certs + cp redis_ca.crt /opt/jumpserver/config/certs/redis_ca.crt + cp redis_client.crt /opt/jumpserver/config/certs/redis_client.crt + cp redis_client.key /opt/jumpserver/config/certs/redis_client.key + ``` + + - Test the Redis connection without errors. + + ```bash + # . /opt/jumpserver/config/config.txt + # redis-cli --tls --cacert /opt/jumpserver/config/certs/redis_ca.crt --cert /opt/jumpserver/config/certs/redis_client.crt --key /opt/jumpserver/config/certs/redis_client.key -h $REDIS_HOST -p $REDIS_PORT -a $REDIS_PASSWORD info + ``` + +### 1.2 Edit Configuration File +!!! tip "" + - Open the configuration file. + + ```bash + vi /opt/jumpserver/config/config.txt + + ``` + + - Configure Redis SSL in the configuration file. + + ```vim + REDIS_USE_SSL=True + ``` + +### 1.3 Restart JumpServer Service +!!! tip "" + ```bash + cd /opt/jumpserver-installer-{{ jumpserver.tag }} + ./jmsctl.sh down + ./jmsctl.sh start + ``` + +!!! warning "For other JumpServer deployment methods, place the Redis SSL certificate in the data/certs directory of each component and restart" + - /opt/jumpserver/data/certs + - /opt/koko/data/certs + - /opt/lion/data/certs diff --git a/docs/installation/setup_kubernetes/helm_online_install.en.md b/docs/installation/setup_kubernetes/helm_online_install.en.md new file mode 100644 index 000000000..375de82b5 --- /dev/null +++ b/docs/installation/setup_kubernetes/helm_online_install.en.md @@ -0,0 +1,50 @@ +# Online Installation + +## 1 Environment Requirements + +- Kubernetes 1.20+ +- Helm 3.0 + +## 2 Install and Deploy +### 2.1 Add JumpServer Helm Repository +!!! tip "" + ```sh + helm repo add jumpserver https://jumpserver.github.io/helm-charts + helm repo list + ``` + +!!! tip "" + | Name | Description | Value | + | :------------------------ | :---------------------------------------------- | :---------------------- | + | global.imageRegistry | Global Docker image registry | docker.io | + | global.imageOwner | Global Docker image owner | jumpserver | + | global.imagePullSecrets | Global Docker registry secret names as an array | [] | + | global.storageClass | Global StorageClass for Persistent Volume(s) | "" | + | externalDatabase.engine | External database engine | postgresql | + | externalDatabase.host | External database host | localhost | + | externalDatabase.port | External database port | 5432 | + | externalDatabase.user | External database user | postgres | + | externalDatabase.password | External database password | postgres | + | externalDatabase.database | External database name | jumpserver | + | core.env.DOMAINS | CSRF_TRUSTED_ORIGINS | "test.jumpserver.org" | + +### 2.2 Edit JumpServer values.yaml File +!!! tip "" + ```sh + helm show values jumpserver/jumpserver > values.yaml + vim values.yaml + ``` + +### 2.3 Install JumpServer + +!!! tip "" + ```sh + helm install jms-k8s jumpserver/jumpserver -n default -f values.yaml + ``` + +### 2.4 Uninstall JumpServer + +!!! tip "" + ```sh + helm uninstall jms-k8s -n default + ``` diff --git a/docs/installation/setup_kubernetes/helm_online_upgrade.en.md b/docs/installation/setup_kubernetes/helm_online_upgrade.en.md new file mode 100644 index 000000000..7f709cb07 --- /dev/null +++ b/docs/installation/setup_kubernetes/helm_online_upgrade.en.md @@ -0,0 +1,14 @@ +# Online Upgrade + +!!! warning "If upgrading JumpServer V3 to V4, you need to upgrade to the latest version of V3 first, otherwise the upgrade will fail!" + +!!! tip "" + - Please manually backup the database first, then proceed with the operation. + - Get values.yaml from https://github.com/jumpserver/helm-charts/blob/main/charts/jumpserver/values.yaml for the specific version configuration file. + - If you don't want to use values.yaml, you can use the --set key=value method to pass parameters + +!!! tip "" + ```sh + helm repo update + helm upgrade jms-k8s jumpserver/jumpserver -n default -f values.yaml + ``` diff --git a/docs/installation/setup_linux_lb/elasticsearch_install.en.md b/docs/installation/setup_linux_lb/elasticsearch_install.en.md new file mode 100644 index 000000000..09f15bfe2 --- /dev/null +++ b/docs/installation/setup_linux_lb/elasticsearch_install.en.md @@ -0,0 +1,54 @@ +# Deploy Elasticsearch Service + +!!! tip "Note" + - This document takes Docker Compose deployment of Elasticsearch as an example. For other installation methods, please refer to https://www.elastic.co/guide/en/elasticsearch/reference/index.html + +## 1 Preparation +### 1.1 Environment Information +!!! tip "" + - Elasticsearch server information is as follows: + + ```sh + 192.168.100.51 + ``` + +## 2 Install and Configure Elasticsearch via Docker Compose + +### 2.1 Create Elasticsearch Data Directory +!!! tip "" + ```sh + mkdir -p /opt/jumpserver/elasticsearch/data /opt/jumpserver/elasticsearch/logs + ``` +### 2.2 Docker Compose Configuration +!!! tip "" + ```vim + Enter a directory convenient for management (e.g., /home/ubuntu) + vim docker-compose.yml + ``` + ```vim + # Please modify the account and password yourself and remember them. + # After losing them, you can delete the container and recreate it with a new password. Data will not be lost. + # ELASTIC_PASSWORD=KXOeyNgDeTdpeu9q # Elasticsearch password + ``` + ```vim + version: '3.8' + ``` +### 2.3 Start Elasticsearch Service +!!! tip "" + ```sh + # Make sure the current directory is where docker-compose.yml is located (e.g., /home/ubuntu) + docker compose up -d + ``` + +## 3 Configure Elasticsearch in JumpServer +!!! tip "" + - Visit the JumpServer web page and log in with your administrator account. + - Click [Terminal Management] in the left menu, select [Storage Configuration] at the top of the page, under [Command Storage] select [Create] and choose [Elasticsearch] + - Fill in according to the instructions below, then on the [Terminal Management] page [Update] all components, select [jms-es] for command storage, and submit. + + | Option | Reference Value | Description | + | :------------- | :------------------------------------------------- | :--------------------- | + | Name | jms-es | Identifier, must be unique | + | Type | Elasticsearch | Fixed, cannot be changed | + | Hosts | https://elastic:KXOeyNgDeTdpeu9q@192.168.100.51:9200 | Elasticsearch service address | + | Default | | New components will automatically use this storage | diff --git a/docs/installation/setup_linux_lb/haproxy_install.en.md b/docs/installation/setup_linux_lb/haproxy_install.en.md new file mode 100644 index 000000000..4de9ea0d4 --- /dev/null +++ b/docs/installation/setup_linux_lb/haproxy_install.en.md @@ -0,0 +1,128 @@ +# Deploy HAProxy Service + +## 1 Preparation +### 1.1 Environment Information +!!! tip "" + - HAProxy server information is as follows: + + ```sh + 192.168.100.100 + ``` + +### 1.2 Install Dependencies +!!! tip "" + The Ubuntu official repository includes HAProxy. No need to install additional EPEL repositories. Just update the system package index: + ```sh + sudo apt update + ``` + +## 2 Install and Configure HAProxy +### 2.1 Install HAProxy +!!! tip "" + ```sh + sudo apt install -y haproxy + ``` + +### 2.2 Configure HAProxy +!!! tip "" + ```sh + # Open the HAProxy configuration file + sudo vim /etc/haproxy/haproxy.cfg + ``` + ```nginx + global + log 127.0.0.1 local2 + chroot /var/lib/haproxy + pidfile /var/run/haproxy.pid + maxconn 4096 + user haproxy + group haproxy + daemon + stats socket /var/lib/haproxy/stats + + defaults + log global + mode tcp + option tcplog + option dontlognull + retries 3 + timeout connect 5000 + timeout client 50000 + timeout server 50000 + maxconn 3000 + + listen stats + bind *:8080 + stats enable + stats uri /haproxy + stats refresh 30s + stats admin if TRUE + stats auth admin:KXOeyNgDeTdpeu9q # Username and password. Please modify. Access http://192.168.100.100:8080/haproxy + + #--------------------------------------------------------------------- + # check parameter description + # inter check interval, unit: milliseconds + # rise consecutive successful checks, unit: times + # fall consecutive failed checks, unit: times + # example: inter 2s rise 2 fall 3 + # means check every 2 seconds, service is normal after 2 consecutive successes, service is abnormal after 3 consecutive failures + # + # server parameter description + # server 192.168.100.21 192.168.100.21:80 weight 1 cookie web01 + # The first 192.168.100.21 is the identifier shown on the page, can be changed to any string + # The second 192.168.100.21:80 is the actual backend service port + # weight is the weight for load balancing among multiple nodes + # cookie identifier will be included in user-side cookies to distinguish which backend node is being accessed + # example: server db01 192.168.100.21:3306 weight 1 cookie db_01 + #--------------------------------------------------------------------- + + listen jms-web + bind *:80 + balance roundrobin + option httpchk GET /api/health/ + default-server inter 2s rise 2 fall 3 + server 192.168.100.21 192.168.100.21:80 weight 1 cookie web01 check + server 192.168.100.22 192.168.100.22:80 weight 1 cookie web02 check + + listen jms-ssh + bind *:2222 + balance roundrobin + default-server inter 2s rise 2 fall 3 + server 192.168.100.21 192.168.100.21:2222 weight 1 cookie ssh01 check + server 192.168.100.22 192.168.100.22:2222 weight 1 cookie ssh02 check + + listen jms-rdp + bind *:3389 + balance roundrobin + default-server inter 2s rise 2 fall 3 + server 192.168.100.21 192.168.100.21:3389 weight 1 cookie rdp01 check + server 192.168.100.22 192.168.100.22:3389 weight 1 cookie rdp02 check + + listen jms-https + bind *:443 + balance roundrobin + option httpchk GET /api/health/ + default-server inter 2s rise 2 fall 3 + server 192.168.100.21 192.168.100.21:443 weight 1 cookie https01 check + server 192.168.100.22 192.168.100.22:443 weight 1 cookie https02 check + ``` + + +### 2.3 Start HAProxy +!!! tip "" + ```sh + sudo systemctl enable haproxy + sudo systemctl start haproxy + sudo systemctl status haproxy + ``` + +## 3 Configure Firewall +!!! tip "" + ```sh + sudo ufw allow 80/tcp + sudo ufw allow 443/tcp + sudo ufw allow 2222/tcp + sudo ufw allow 3389/tcp + sudo ufw allow 8080/tcp + sudo ufw reload + ``` diff --git a/docs/installation/setup_linux_lb/installation_node01.en.md b/docs/installation/setup_linux_lb/installation_node01.en.md new file mode 100644 index 000000000..6390bcf67 --- /dev/null +++ b/docs/installation/setup_linux_lb/installation_node01.en.md @@ -0,0 +1,59 @@ +# Deploy JumpServer Node 01 + +## 1 Preparation +### 1.1 Environment Information +!!! tip "" + - JumpServer_Node_01 server information is as follows: + + ```sh + 192.168.100.21 + ``` + +## 2 Configure NFS +### 2.1 Install NFS Dependency Packages +!!! tip "" + ```sh + yum -y install nfs-utils + showmount -e 192.168.100.11 + ``` + +### 2.2 Mount NFS Directory +!!! tip "" + ```sh + # Mount the Core persistence directory to NFS. The default is /data/jumpserver/core/data. Modify according to actual situation. + # JumpServer persistence directory definition is related to parameter VOLUME_DIR. You will be prompted during JumpServer installation. + mkdir /data/jumpserver/core/data + mount -t nfs 192.168.100.11:/data /data/jumpserver/core/data + ``` + +### 2.3 Configure Automatic NFS Mount on Boot +!!! tip "" + ```sh + # Write to /etc/fstab for automatic mounting on reboot. Note: After setting this, if NFS is corrupted or cannot be connected, the server will fail to start. + echo "192.168.100.11:/data /data/jumpserver/core/data nfs defaults 0 0" >> /etc/fstab + ``` + +## 3 Install JumpServer + +### 3.1 Download Installation Package +!!! tip "" + - Download the latest linux/amd64 offline package from the Fei Zhi Yun community [downloads page](https://community.fit2cloud.com/#/products/jumpserver/downloads){:target="_blank"}, and upload it to the /opt directory of the deployment server. + +### 3.2 Install JumpServer Service +!!! tip "" + ```sh + ./jmsctl.sh install + ``` + +!!! warning "Note: The bootstrap_token and SECRET_KEY in the configuration file must be consistent with other JumpServer nodes in the cluster, otherwise database data and component registration will be affected. During the first installation, random values will be automatically generated. After Node 01 completes installation, these values need to be recorded and used in other nodes." + +### 3.3 Start JumpServer Service +!!! tip "" + ```sh + ./jmsctl.sh start + ``` + +## 4 Extend More Nodes +!!! tip "" + - To extend more nodes, follow the same installation and configuration as above. + - Ensure that the BOOTSTRAP_TOKEN and SECRET_KEY in the configuration files remain consistent across all nodes. diff --git a/docs/installation/setup_linux_lb/installation_node02.en.md b/docs/installation/setup_linux_lb/installation_node02.en.md new file mode 100644 index 000000000..ddd107ad1 --- /dev/null +++ b/docs/installation/setup_linux_lb/installation_node02.en.md @@ -0,0 +1,76 @@ +# Deploy JumpServer Node 02 + +## 1 Preparation +### 1.1 Environment Information +!!! tip "" + - JumpServer_Node_02 server information is as follows: + ```sh + 192.168.100.22 + ``` + + +## 2 Configure NFS +### 2.1 Install NFS Dependency Packages +!!! tip "" + ```sh + apt -y install nfs-utils + showmount -e 192.168.100.11 + ``` + +### 2.2 Mount NFS Directory +!!! tip "" + ```sh + # Mount the Core persistence directory to NFS. The default is /opt/jumpserver/core/data. Modify according to actual situation. + # JumpServer persistence directory definition is related to parameter VOLUME_DIR. You will be prompted during JumpServer installation. + mkdir /opt/jumpserver/core/data + mount -t nfs 192.168.100.11:/data /opt/jumpserver/core/data + ``` + +### 2.3 Configure Automatic NFS Mount on Boot +!!! tip "" + ```sh + # Write to /etc/fstab for automatic mounting on reboot. Note: After setting this, if NFS is corrupted or cannot be connected, the server will fail to start. + echo "192.168.100.11:/data /opt/jumpserver/core/data nfs defaults 0 0" >> /etc/fstab + ``` + +## 3 Install JumpServer +### 3.1 Download Installation Package +!!! tip "" + - Download the latest linux/amd64 offline package from the Fei Zhi Yun community [downloads page](https://community.fit2cloud.com/#/products/jumpserver/downloads){:target="_blank"}, and upload it to the /opt directory of the deployment server. +### 3.2 Modify Temporary Configuration File +!!! tip "" + ```sh + vi config-example.txt + ``` + ```vim hl_lines="9 10" + + # Modify the options below. Keep others default. Do not directly copy content from here. + # The bootstrap_token and SECRET_KEY in the configuration file must be consistent with other JumpServer nodes in the cluster, otherwise database data and component registration will be affected. + + # Installation Configuration + ### Note the persistence directory VOLUME_DIR. If you mounted NFS to another directory above, modify it here as well. + # For example, if NFS is mounted to /data/jumpserver/core/data, then VOLUME_DIR=/data/jumpserver + VOLUME_DIR=/data/jumpserver + + # Core Configuration + ### Cannot be modified after startup, otherwise passwords and other information cannot be decrypted. Do not directly copy the following string. + SECRET_KEY=kWQdmdCQKjaWlHYpPhkNQDkfaRulM6YnHctsHLlSPs8287o2kW # Must be consistent with other JumpServer nodes (*) + BOOTSTRAP_TOKEN=KXOeyNgDeTdpeu9q # Must be consistent with other JumpServer nodes (*) + ``` + +### 3.3 Execute Script to Install JumpServer Service +!!! tip "" + ```sh + ./jmsctl.sh install + ``` + +### 3.4 Start JumpServer Service +!!! tip "" + ```sh + ./jmsctl.sh start + ``` + +## 4 Extend More Nodes +!!! tip "" + - For additional node expansion, the installation and configuration are the same as above. + - Ensure that the BOOTSTRAP_TOKEN and SECRET_KEY in the configuration files remain consistent across all nodes. diff --git a/docs/installation/setup_linux_lb/linux_lb_upgrade.en.md b/docs/installation/setup_linux_lb/linux_lb_upgrade.en.md new file mode 100644 index 000000000..3166d3d56 --- /dev/null +++ b/docs/installation/setup_linux_lb/linux_lb_upgrade.en.md @@ -0,0 +1,24 @@ +# Upgrade Notes + +## 1 About Cluster Mode Environment Upgrades +!!! warning "Be sure to backup before upgrading" + - Close all JumpServer nodes before upgrading. + - Complete the upgrade operation on any one JumpServer node according to the upgrade documentation. + - Carefully check the upgrade process of this node to ensure there are no issues. + - Then upgrade other JumpServer nodes according to the upgrade documentation. + +!!! tip "" + - Download the latest linux/amd64 offline package from the Fei Zhi Yun community [downloads page](https://community.fit2cloud.com/#/products/jumpserver/downloads){:target="_blank"}, and upload it to the /opt directory of the deployment server. + +!!! tip "" + ```sh + cd /opt + tar -xf jumpserver-offline-installer-{{ jumpserver.tag }}-amd64.tar.gz + cd jumpserver-offline-installer-{{ jumpserver.tag }}-amd64 + ``` + ```sh + # Additional nodes can set SKIP_BACKUP_DB=1 to skip database backup. Do not skip backup for the first upgraded node. + export SKIP_BACKUP_DB=1 + ./jmsctl.sh upgrade + ./jmsctl.sh start + ``` diff --git a/docs/installation/setup_linux_lb/minio_install.en.md b/docs/installation/setup_linux_lb/minio_install.en.md new file mode 100644 index 000000000..babfa3dd0 --- /dev/null +++ b/docs/installation/setup_linux_lb/minio_install.en.md @@ -0,0 +1,58 @@ +# Deploy MinIO Service + +!!! tip "Note" + - This document takes Docker Compose deployment of MinIO as an example. For other installation methods, please refer to https://docs.min.io/docs/minio-quickstart-guide + +## 1 Preparation +### 1.1 Environment Information +!!! tip "" + - MinIO server information is as follows: + + ```sh + 192.168.100.41 + ``` +## 2 Install and Configure MinIO via Docker Compose +### 2.1 Create MinIO Data Persistence Directory +!!! tip "" + ```sh + sudo mkdir -p /opt/jumpserver/minio/data /opt/jumpserver/minio/config + ``` +### 2.2 Docker Compose Configuration +!!! tip "" + ```vim + # Please modify the account and password yourself and remember them. + # After losing them, you can delete the container and recreate it with a new password. Data will not be lost. + # MINIO_ROOT_USER=minio # MinIO username + # MINIO_ROOT_PASSWORD=KXOeyNgDeTdpeu9q # MinIO password + ``` + ```vim + version: '3.8' + ``` +### 2.3 Start MinIO Service +!!! tip "" + ```sh + cd /opt/jumpserver + docker compose up -d + ``` + +## 3 MinIO Configuration +### 3.1 Create Buckets in MinIO +!!! tip "" + - Visit http://192.168.100.41:9000 and log in with the MinIO credentials you set earlier. + - Click the Buckets menu on the left side, select Create Bucket, enter jumpserver as the Bucket Name, then click Save. + +### 3.2 Configure MinIO in JumpServer +!!! tip "" + - Visit the JumpServer web page and log in with your administrator account. + - Click [Terminal Management] in the left menu, select [Storage Configuration] at the top of the page, under [Recording Storage] select [Create] and choose [Ceph] + - Fill in according to the instructions below, then on the [Terminal Management] page [Update] all components, select [jms-minio] for recording storage, and submit. + + | Option | Reference Value | Description | + | :------------- | :------------------------- | :------------------ | + | Name | jms-minio | Identifier, must be unique | + | Type | Ceph | Fixed, cannot be changed | + | Bucket | jumpserver | Bucket Name | + | Access Key (AK) | minio | MINIO_ROOT_USER | + | Access Key Secret (SK) | KXOeyNgDeTdpeu9q | MINIO_ROOT_PASSWORD | + | Endpoint | http://192.168.100.41:9000 | MinIO service access address | + | Default | | New components will automatically use this storage | diff --git a/docs/installation/setup_linux_lb/nfs_install.en.md b/docs/installation/setup_linux_lb/nfs_install.en.md new file mode 100644 index 000000000..e6cbecedc --- /dev/null +++ b/docs/installation/setup_linux_lb/nfs_install.en.md @@ -0,0 +1,55 @@ +# Deploy NFS Service + +## 1 NFS Server Installation and Configuration +### 1.1 Environment Information +!!! tip "" + - NFS server information is as follows: + + ```sh + 192.168.100.11 + ``` + +### 1.2 Install NFS Server Software +!!! tip "" + ```sh + sudo apt update + sudo apt install nfs-kernel-server -y + ``` + + +### 1.3 Start NFS +!!! tip "" + ```sh + sudo systemctl enable nfs-kernel-server + sudo systemctl start nfs-kernel-server + sudo systemctl status nfs-kernel-server + ``` + +### 1.4 Configure Firewall +!!! tip "" + ```sh + sudo ufw allow nfs + sudo ufw allow mountd + sudo ufw allow rpc-bind + sudo ufw status + ``` + +### 1.5 Configure NFS +!!! tip "" + ```sh + mkdir /data + chmod 777 -R /data + + vi /etc/exports + ``` + ```vim + # Set NFS access permissions. /data is the directory to be shared. 192.168.100.* means all assets in the 192.168.100.* segment have the permissions in parentheses. + # You can also write specific authorization targets: /data 192.168.100.30(rw,sync,no_root_squash) 192.168.100.31(rw,sync,no_root_squash) + /data 192.168.100.*(rw,sync,all_squash,anonuid=0,anongid=0) + ``` + +### 1.6 Make the exports Configuration Effective +!!! tip "" + ```sh + sudo exportfs -ra + ``` diff --git a/docs/installation/setup_linux_lb/pgsql_install.en.md b/docs/installation/setup_linux_lb/pgsql_install.en.md new file mode 100644 index 000000000..5f6b8b843 --- /dev/null +++ b/docs/installation/setup_linux_lb/pgsql_install.en.md @@ -0,0 +1,79 @@ +# Deploy PostgreSQL 16 Service + +## 1 Preparation +### 1.1 Environment Information +!!! tip "" + - PostgreSQL server information is as follows: + + ```sh + 192.168.100.11 + ``` + +### 1.2 Set Up Repository +!!! tip "" + ```sh + sudo apt update + sudo apt install -y wget gnupg2 + sudo sh -c 'echo "deb https://apt.postgresql.org/pub/repos/apt $(lsb_release -cs)-pgdg main" > /etc/apt/sources.list.d/pgdg.list' + curl -fsSL https://www.postgresql.org/media/keys/ACCC4CF8.asc|sudo gpg --dearmor -o /etc/apt/trusted.gpg.d/postgresql.gpg + sudo apt update + ``` + +## 2 Install and Configure PostgreSQL +### 2.1 Install PostgreSQL via APT +!!! tip "" + ```sh + sudo apt install -y postgresql-16 + ``` + +### 2.2 Start PostgreSQL +!!! tip "" + ```sh + sudo systemctl enable postgresql + sudo systemctl start postgresql + sudo systemctl status postgresql + ``` + +### 2.3 Configure Database Authorization +!!! tip "" + ```sh + sudo -u postgres psql + ``` + ```sql + CREATE DATABASE jumpserver; + CREATE USER jumpserver WITH PASSWORD 'KXOeyNgDeTdpeu9q'; + GRANT ALL PRIVILEGES ON DATABASE jumpserver TO jumpserver; + \q + ``` + +### 2.4 Configure Remote Access +!!! tip "" + ```sh + sudo vim /etc/postgresql/16/main/postgresql.conf + ``` + Find and modify: + ```vim + listen_addresses = '*' + ``` +### 2.5 Configure Client Authentication +!!! tip "" + ```sh + sudo vim /etc/postgresql/16/main/pg_hba.conf + ``` + Add at the end: + ```vim + host all all 0.0.0.0/0 md5 + ``` + Restart the service to take effect: + ```sh + sudo systemctl restart postgresql + sudo systemctl status postgresql + ``` + + +## 3 Configure Firewall +!!! tip "" + ```sh + sudo ufw allow from 192.168.100.0/24 to any port 5432 + sudo ufw reload + ``` diff --git a/docs/installation/setup_linux_lb/redis_install.en.md b/docs/installation/setup_linux_lb/redis_install.en.md new file mode 100644 index 000000000..a28dba984 --- /dev/null +++ b/docs/installation/setup_linux_lb/redis_install.en.md @@ -0,0 +1,47 @@ +# Deploy Redis Service + +## 1 Preparation +### 1.1 Environment Information +!!! tip "" + - Redis server information is as follows: + + ```sh + 192.168.100.11 + ``` + +### 1.2 Update System Package Index +!!! tip "" + ```sh + sudo apt update + ``` + +## 2 Install and Configure Redis +### 2.1 Install Redis via APT +!!! tip "" + ```sh + sudo apt install -y redis-server + ``` + +### 2.2 Configure Redis +!!! tip "" + ```sh + sudo vim /etc/redis/redis.conf + ``` + ```vim + requirepass KXOeyNgDeTdpeu9q # Set password (already exists, uncomment) + bind 127.0.0.1 # Comment out this line to enable remote access + ``` + +### 2.3 Start Redis +!!! tip "" + ```sh + systemctl enable redis + systemctl start redis + ``` + +## 3 Configure Firewall +!!! tip "" + ```sh + sudo ufw allow from 192.168.100.0/24 to any port 6379 proto tcp + sudo ufw reload + ``` diff --git a/docs/installation/setup_linux_lb/requirements.en.md b/docs/installation/setup_linux_lb/requirements.en.md new file mode 100644 index 000000000..9fcd4e0af --- /dev/null +++ b/docs/installation/setup_linux_lb/requirements.en.md @@ -0,0 +1,58 @@ +# Preparation Guide + +## 1 Overall Deployment Description +!!! tip "Environment Description" + - Except for JumpServer's own components, the high availability of other components should be deployed according to the official documentation of the corresponding project. + - After deployment in this manner, you only need to scale JumpServer nodes as needed and add the nodes to HAProxy. + - If you already have an HLB or SLB, you can skip the HAProxy deployment. Third-party LB needs to pay attention to session and websocket issues. + - If you already have cloud storage (S3/Ceph/Swift/OSS/Azure), you can skip MinIO deployment. The same applies to MySQL and Redis. + - In production environments, you should use Ceph to replace NFS, or deploy high-availability NFS to prevent single point of failure. + - This document is a reference document. Specific architecture needs to be designed according to your needs. + +### 1.1 Database Requirements +!!! tip "" + + | Name | Version | Default Charset | Default Collation | TLS/SSL | + | :------ | :------ | :--------------- | :----------------- | :--------------- | + | PostgreSQL | 16 | utf8 | utf8_general_ci | :material-check: | + | MariaDB | >= 10.6 | utf8mb3 | utf8mb3_general_ci | :material-check: | + + | Name | Version | Sentinel | Cluster | TLS/SSL | + | :------ | :------ | :--------------- | :----------------- | :--------------- | + | Redis | >= 6.0 | :material-check: | :material-close: | :material-check: | + +### 1.2 Server Requirements +!!! tip "" + + | Service Name | IP Address | Port | Components/Services Used | Minimum Hardware Config | Standard Hardware Config | + | ------------- | ---------------- | ----------------------- | ---------------- | ---------------------- | ----------------------- | + | NFS | 192.168.100.11 | - | Core | 2Core/8GB RAM/100G HDD | 4Core/16GB RAM/1T SSD | + | PostgreSQL | 192.168.100.11 | 5432 | Core | 2Core/4GB RAM/100G HDD | 4Core/8GB RAM/500G SSD | + | Redis | 192.168.100.11 | 6379 | Core, KoKo, Lion | 2Core/4GB RAM/100G HDD | 4Core/8GB RAM/500G SSD | + | HAProxy | 192.168.100.100 | 80,443,2222,3389 | All | 2Core/4GB RAM/20G HDD | 2Core/4GB RAM/20G HDD | + | JumpServer 01 | 192.168.100.21 | 80,443,2222,3389 | All | 4Core/8GB RAM/100G HDD | 8Core/16GB RAM/200G SSD | + | JumpServer 02 | 192.168.100.22 | 80,443,2222,3389 | All | 4Core/8GB RAM/100G HDD | 8Core/16GB RAM/200G SSD | + | MinIO | 192.168.100.41 | 9000,9001 | Core | 2Core/4GB RAM/100G HDD | 4Core/8GB RAM/1T SSD | + | Elasticsearch | 192.168.100.51 | 9200,9300 | Core, KoKo | 2Core/4GB RAM/100G HDD | 4Core/8GB RAM/1T SSD | + +### 1.3 Component Container Health Check +!!! tip "" + + | Component | Health Check Endpoint URL | Demo | + | ------------- | ----------------------------------- | -------------------------------------- | + | Core | http://core:8000/api/health/ | https://demo.jumpserver.org/api/health/ | + | KoKo | http://koko:5000/health/ | https://demo.jumpserver.org/koko/health/ | + | Lion | http://lion:8081/lion/health/ | https://demo.jumpserver.org/lion/health/ | + +## 2 Deployment Order +!!! tip "" + 1. Deploy NFS service + 2. Deploy PostgreSQL service + 3. Deploy Redis service + 4. Deploy HAProxy service + 5. Deploy JumpServer 01 node + 6. Deploy JumpServer 02 node + 7. Deploy MinIO service + 8. Deploy Elasticsearch service + 9. Configure JumpServer components + 10. Deploy Elasticsearch service diff --git a/docs/installation/source_install/core_install.en.md b/docs/installation/source_install/core_install.en.md new file mode 100644 index 000000000..663ad3647 --- /dev/null +++ b/docs/installation/source_install/core_install.en.md @@ -0,0 +1,71 @@ +# Core Environment Deployment + +## 1 Core Component Overview + +!!! tip "" + - [Core][core] is the core component of JumpServer, developed based on [Django][django], with built-in [Gunicorn][gunicorn], [Celery][celery], Beat, [Flower][flower], and [Daphne][daphne] services. + +### 1.1 Environment Requirements + +!!! tip "" + | Component | Version | Python Version | + | --- | --- | --- | + | Core | v4.10.9 | 3.9+ | + +### 1.2 Download Source Code + +!!! tip "" + - Download the latest [Release][core_release] from the [Github][core] website. These versions are stable snapshots of the latest code. Downloaded sources are in .tar.gz archive format; extract using: + + ```bash + cd /opt + wget https://github.com/jumpserver/jumpserver/releases/download/v4.10.9/jumpserver-v4.10.9.tar.gz + tar xf jumpserver-v4.10.9.tar.gz + cd jumpserver-v4.10.9 + ``` + +### 1.3 Install Python3 + +!!! tip "" + - Get Python3 deployment methods from the [Python][python] website. Verify installation completion according to [environment requirements](#_3) by: + + ```bash + python3 --version + # Python 3.9.0 + ``` + +### 1.4 Install Python Dependencies + +!!! tip "" + - Create a dedicated Python virtual environment for the JumpServer project: + + ```bash + python3 -m venv /opt/py3 + source /opt/py3/bin/activate + pip install -r requirements/requirements.txt + ``` + +### 1.5 Start Core + +!!! tip "" + - To run in background, add -d: `./jms start -d` + + ```bash + cd /opt/jumpserver-v4.10.9 + ./jms start + ``` + +[nginx]: http://nginx.org/ +[lina]: https://github.com/jumpserver/lina/ +[vue]: https://cn.vuejs.org/ +[element_ui]: https://element.eleme.cn/ +[luna]: https://github.com/jumpserver/luna/ +[angular_cli]: https://github.com/angular/angular-cli +[core]: https://github.com/jumpserver/jumpserver/ +[django]: https://docs.djangoproject.com/ +[gunicorn]: https://gunicorn.org/ +[celery]: https://docs.celeryproject.org/ +[flower]: https://github.com/mher/flower/ +[daphne]: https://github.com/django/daphne/ +[python]: https://www.python.org/downloads/ +[core_release]: https://github.com/jumpserver/jumpserver/releases/tag/v4.10.9 diff --git a/docs/installation/source_install/koko_install.en.md b/docs/installation/source_install/koko_install.en.md new file mode 100644 index 000000000..0d37fa171 --- /dev/null +++ b/docs/installation/source_install/koko_install.en.md @@ -0,0 +1,52 @@ +# KoKo Environment Deployment + +## 1 KoKo Component Overview + +!!! tip "" + KoKo is the Go version of coco, which reconstructed coco's SSH/SFTP service and Web Terminal service. + +### 1.1 Environment Requirements + +!!! tip "" + | Component | Version | Go Version | Node Version | Redis Version | + | --- | --- | --- | --- | --- | + | KoKo | v4.10.9 | 1.18+ | 16.5+ | >= 6.0 | + +### 1.2 Select Deployment Method + +!!! tip "" + === "Source Code Deployment" + - Download from [GitHub][koko] releases + - Extract and configure + +### 1.3 Modify Configuration File + +!!! tip "" + ```bash + cd /opt/koko + vi config.yml + ``` + Configure database, Redis, and other settings as needed. + +### 1.4 Start KoKo + +!!! tip "" + ```bash + cd /opt/koko + ./koko + ``` + +[nginx]: http://nginx.org/ +[lina]: https://github.com/jumpserver/lina/ +[vue]: https://cn.vuejs.org/ +[element_ui]: https://element.eleme.cn/ +[luna]: https://github.com/jumpserver/luna/ +[angular_cli]: https://github.com/angular/angular-cli +[core]: https://github.com/jumpserver/jumpserver/ +[koko]: https://github.com/jumpserver/koko +[django]: https://docs.djangoproject.com/ +[gunicorn]: https://gunicorn.org/ +[celery]: https://docs.celeryproject.org/ +[flower]: https://github.com/mher/flower/ +[daphne]: https://github.com/django/daphne/ +[go]: https://golang.google.cn/ diff --git a/docs/installation/source_install/lina_install.en.md b/docs/installation/source_install/lina_install.en.md new file mode 100644 index 000000000..71906d0b2 --- /dev/null +++ b/docs/installation/source_install/lina_install.en.md @@ -0,0 +1,31 @@ +# Lina Environment Deployment + +## 1 Lina Component Overview + +!!! tip "" + - [Lina][lina] is the JumpServer frontend UI project, primarily using [Vue][vue] and [Element UI][element_ui]. + +### 1.1 Environment Requirements + +!!! tip "" + | Component | Version | Node Version | + | --- | --- | --- | + | Lina | v4.10.9 | 16.5+ | + +### 1.2 Select Deployment Method + +!!! tip "" + === "Source Code Deployment" + - Download from [GitHub][lina] releases + - Install dependencies: `npm install` + - Build: `npm run build` + +[nginx]: http://nginx.org/ +[lina]: https://github.com/jumpserver/lina/ +[vue]: https://cn.vuejs.org/ +[element_ui]: https://element.eleme.cn/ +[luna]: https://github.com/jumpserver/luna/ +[angular_cli]: https://github.com/angular/angular-cli +[core]: https://github.com/jumpserver/jumpserver/ +[node]: https://nodejs.org/ +[lina_release]: https://github.com/jumpserver/lina/releases/tag/v4.10.9 diff --git a/docs/installation/source_install/lion_install.en.md b/docs/installation/source_install/lion_install.en.md new file mode 100644 index 000000000..06a78a09a --- /dev/null +++ b/docs/installation/source_install/lion_install.en.md @@ -0,0 +1,69 @@ +# Lion Environment Deployment + +## 1 Lion Component Overview + +!!! tip "" + [Lion][lion] uses the open-source project [Guacamole][guacamole] from the [Apache][apache] Software Foundation. JumpServer reconstructed Guacamole using Golang and Vue to implement RDP/VNC protocol bastion machine functionality. + +### 1.1 Environment Requirements + +!!! tip "" + - Ubuntu 20.04 LTS or later + - Guacd compiled from source + +### 1.2 Build Guacd + +!!! tip "" + ```bash + cd /opt + git clone https://github.com/apache/guacamole-server + cd guacamole-server + ./configure + make + make install + ``` + - To use systemd management: `./configure --with-systemd-dir=/etc/systemd/system/` + +### 1.3 Download Lion + +!!! tip "" + - Download the latest [Release][lion_release] from [Github][lion]. + + | Platform | Architecture | Download Link | + | --- | --- | --- | + | Linux | amd64 | [lion-v4.10.9-linux-amd64.tar.gz][lion_release] | + | Windows | amd64 | [lion-v4.10.9-windows-amd64.tar.gz][lion_release] | + +### 1.4 Modify Configuration File + +!!! tip "" + ```bash + cd /opt/lion + vi config.toml + ``` + Configure server, database, Redis settings as needed. + +### 1.5 Start Guacd + +!!! tip "" + ```bash + guacd -d + ``` + +### 1.6 Start Lion + +!!! tip "" + ```bash + cd /opt/lion + ./lion + ``` + +[nginx]: http://nginx.org/ +[lina]: https://github.com/jumpserver/lina/ +[luna]: https://github.com/jumpserver/luna/ +[angular_cli]: https://github.com/angular/angular-cli +[core]: https://github.com/jumpserver/jumpserver/ +[lion]: https://github.com/jumpserver/lion +[lion_release]: https://github.com/jumpserver/lion/releases +[apache]: https://www.apache.org/ +[guacamole]: https://guacamole.apache.org/ diff --git a/docs/installation/source_install/luna_install.en.md b/docs/installation/source_install/luna_install.en.md new file mode 100644 index 000000000..b63b3f589 --- /dev/null +++ b/docs/installation/source_install/luna_install.en.md @@ -0,0 +1,31 @@ +# Luna Environment Deployment + +## 1 Luna Component Overview + +!!! tip "" + [Luna][luna] is the JumpServer frontend UI project, primarily using [Angular CLI][angular_cli]. + +### 1.1 Environment Requirements + +!!! tip "" + | Component | Version | Node Version | + | --- | --- | --- | + | Luna | v4.10.9 | 16.5+ | + +### 1.2 Select Deployment Method + +!!! tip "" + === "Source Code Deployment" + - Download from [GitHub][luna] releases + - Install dependencies: `npm install` + - Build: `npm run build` + +[nginx]: http://nginx.org/ +[lina]: https://github.com/jumpserver/lina/ +[vue]: https://cn.vuejs.org/ +[element_ui]: https://element.eleme.cn/ +[luna]: https://github.com/jumpserver/luna/ +[angular_cli]: https://github.com/angular/angular-cli +[core]: https://github.com/jumpserver/jumpserver/ +[node]: https://nodejs.org/ +[luna_release]: https://github.com/jumpserver/luna/releases/tag/v4.10.9 diff --git a/docs/installation/source_install/magnus_install.en.md b/docs/installation/source_install/magnus_install.en.md new file mode 100644 index 000000000..6300d9931 --- /dev/null +++ b/docs/installation/source_install/magnus_install.en.md @@ -0,0 +1,42 @@ +# Magnus Environment Deployment + +## 1 Magnus Environment Deployment + +### 1.1 Environment Requirements + +!!! tip "" + - Download the latest [Release][magnus_release] from [Github][magnus]. + + | Platform | Architecture | Download Link | + | --- | --- | --- | + | Linux | amd64 | [magnus-v4.10.9-linux-amd64.tar.gz][magnus_release] | + | macOS | x86_64 | [magnus-v4.10.9-darwin-x86_64.tar.gz][magnus_release] | + | macOS | arm64 | [magnus-v4.10.9-darwin-arm64.tar.gz][magnus_release] | + +!!! tip "" + - Magnus requires Wisp to communicate with JumpServer. Download the latest [Release][wisp_release] from [Github][wisp]. + + | Platform | Architecture | Download Link | + | --- | --- | --- | + | Linux | amd64 | [wisp-v1.0.0-linux-amd64.tar.gz][wisp_release] | + | macOS | x86_64 | [wisp-v1.0.0-darwin-x86_64.tar.gz][wisp_release] | + | Windows | amd64 | [wisp-v1.0.0-windows-amd64.tar.gz][wisp_release] | + +### 1.2 Select Deployment Method + +!!! tip "" + === "Linux/amd64" + - Extract and configure + - Start Magnus and Wisp services + +[nginx]: http://nginx.org/ +[lina]: https://github.com/jumpserver/lina/ +[vue]: https://cn.vuejs.org/ +[element_ui]: https://element.eleme.cn/ +[luna]: https://github.com/jumpserver/luna/ +[angular_cli]: https://github.com/angular/angular-cli +[core]: https://github.com/jumpserver/jumpserver/ +[magnus]: https://github.com/jumpserver/magnus +[magnus_release]: https://github.com/jumpserver/magnus/releases +[wisp]: https://github.com/jumpserver/wisp +[wisp_release]: https://github.com/jumpserver/wisp/releases diff --git a/docs/installation/source_install/merge_jumpserver.en.md b/docs/installation/source_install/merge_jumpserver.en.md new file mode 100644 index 000000000..c8ae91bb0 --- /dev/null +++ b/docs/installation/source_install/merge_jumpserver.en.md @@ -0,0 +1,123 @@ +# JumpServer Environment Integration + +## 1 Operation Process + +### 1.1 Edit Configuration File + +!!! tip "" + ```bash + vi /etc/nginx/conf.d/jumpserver.conf + ``` + +### 1.2 Select Deployment Method + +!!! tip "" + === "Source Code Deployment" + + ```nginx + server { + listen 80; + server_name _; + client_max_body_size 5000m; + + # Luna Configuration + location /luna/ { + proxy_pass http://localhost:4200; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + } + + # Core Static Resources + location /media/replay/ { + add_header Content-Encoding gzip; + root /opt/jumpserver-v4.10.9/data/; + } + + location /static/ { + root /opt/jumpserver-v4.10.9/data/; + } + + # KoKo Lion Configuration + location /koko/ { + proxy_pass http://localhost:2222; + proxy_http_version 1.1; + proxy_buffering off; + proxy_request_buffering off; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + } + + # Lion Configuration + location /lion/ { + proxy_pass http://localhost:8081; + proxy_http_version 1.1; + proxy_buffering off; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + } + + # Core Configuration + location / { + proxy_pass http://localhost:8000; + proxy_http_version 1.1; + proxy_buffering off; + proxy_request_buffering off; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + proxy_set_header X-Forwarded-Proto $scheme; + } + } + ``` + + === "Using Release" + + ```nginx + server { + listen 80; + server_name _; + client_max_body_size 5000m; + + # Luna Configuration + location /luna/ { + alias /opt/jumpserver-v4.10.9/lina/; + try_files $uri $uri/ /luna/index.html; + } + + # Lina Configuration + location / { + alias /opt/jumpserver-v4.10.9/lina/; + try_files $uri $uri/ /index.html; + } + + # Core Static Resources + location /media/replay/ { + add_header Content-Encoding gzip; + root /opt/jumpserver-v4.10.9/; + } + + location /static/ { + root /opt/jumpserver-v4.10.9/; + } + + # KoKo Configuration + location /koko/ { + proxy_pass http://127.0.0.1:2222; + proxy_http_version 1.1; + proxy_set_header Upgrade $http_upgrade; + proxy_set_header Connection "upgrade"; + } + + # Core API Configuration + location /api/ { + proxy_pass http://127.0.0.1:8000; + proxy_http_version 1.1; + proxy_set_header X-Real-IP $remote_addr; + proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for; + } + } + ``` + + ```bash + nginx -t + nginx -s reload + ``` diff --git a/docs/installation/source_install/nginx_install.en.md b/docs/installation/source_install/nginx_install.en.md new file mode 100644 index 000000000..2184d1052 --- /dev/null +++ b/docs/installation/source_install/nginx_install.en.md @@ -0,0 +1,31 @@ +# Nginx Environment Deployment + +## 1 Operation Process + +!!! tip "" + - Get the latest Nginx release from [Nginx][nginx] official website [linux_packages][linux_packages]. Verify installation completion via: + ```bash + nginx -v + # nginx version: nginx/1.20.2 + ``` + +!!! tip "" + - For CentOS/RHEL systems: + ```bash + yum install -y nginx + systemctl start nginx + systemctl enable nginx + ``` + +!!! tip "" + - For Ubuntu/Debian systems: + ```bash + apt-get update + apt-get install -y nginx + systemctl start nginx + systemctl enable nginx + ``` + +[nginx]: http://nginx.org/ +[lina]: https://github.com/jumpserver/lina/ +[linux_packages]: http://nginx.org/en/linux_packages.html diff --git a/docs/installation/source_install/requirements.en.md b/docs/installation/source_install/requirements.en.md new file mode 100644 index 000000000..fcfc13e1d --- /dev/null +++ b/docs/installation/source_install/requirements.en.md @@ -0,0 +1,44 @@ +# Environment Instructions + +!!! warning "Windows platform recommends using VSCode's Remote SSH feature to compile on Linux" + +## 1 Architecture Diagram + +!!! tip "" + - JumpServer is divided into multiple components. The rough architecture is shown in the figure below. [Lina][lina] and [Luna][luna] are pure static files, ultimately integrated by [Nginx][nginx]. +![Architecture Diagram](../../img/architecture.png) + +## 2 Database Requirements + +!!! tip "" + - Choose between MySQL and MariaDB; JumpServer needs to use MySQL or MariaDB to store data. + + | Component | Version | MySQL Version | MariaDB Version | Redis Version | + | --- | --- | --- | --- | --- | + | JumpServer | v4.10.9 | >= 5.7 | >= 10.3 | >= 6.0 | + +## 3 Deployment Order + +!!! tip "" + 1. Core environment deployment + 2. KoKo environment deployment + 3. Lina environment deployment + 4. Luna environment deployment + 5. Lion environment deployment + 6. Magnus environment deployment + 7. Nginx environment deployment + 8. JumpServer environment integration + +[nginx]: http://nginx.org/ +[lina]: https://github.com/jumpserver/lina/ +[vue]: https://cn.vuejs.org/ +[element_ui]: https://element.eleme.cn/ +[luna]: https://github.com/jumpserver/luna/ +[angular_cli]: https://github.com/angular/angular-cli +[core]: https://github.com/jumpserver/jumpserver/ +[django]: https://docs.djangoproject.com/ +[gunicorn]: https://gunicorn.org/ +[celery]: https://docs.celeryproject.org/ +[flower]: https://github.com/mher/flower/ +[daphne]: https://github.com/django/daphne/ +[python]: https://www.python.org/downloads/ diff --git a/docs/installation/upgrade_notice.en.md b/docs/installation/upgrade_notice.en.md new file mode 100644 index 000000000..f4cac66af --- /dev/null +++ b/docs/installation/upgrade_notice.en.md @@ -0,0 +1,40 @@ +# Upgrade Notice + +!!! warning "There are certain differences between v3 and v2 versions. If upgrading from v2 to v3 [please read this document first](https://kb.fit2cloud.com/?p=06638d69-f109-4333-b5bf-65b17b297ed9){:target="_blank\"}" + +!!! warning "Versions v2.20 =< Version <= v2.23 need to upgrade to v2.28 first, then upgrade to v3, otherwise asset connection failures will occur" + +!!! warning "Note" + **v3.6 version requires mandatory DOMAINS trusted domain name configuration for normal service access; otherwise error code 400/403 will prevent page access. DOMAINS configuration is as follows:** + + - If the server is one-click installed and the old version already uses JumpServer with HTTPS enabled, no changes are needed. + - For scenarios needing to access JumpServer using IP addresses, fill in the DOMAINS field in the config.txt configuration file according to your IP type (public IP or private IP). + + ``` + # Open config.txt configuration file and define DOMAINS field + DOMAINS=jumpserver.example.com,192.168.1.1 + jmsctl restart + ``` + +!!! info "Backup before upgrade or migration operations" + +!!! warning "Note" + - Be sure to backup before updating + - [For upgrading from V2 to V3, refer to this document](https://kb.fit2cloud.com/?p=06638d69-f109-4333-b5bf-65b17b297ed9){:target="_blank"} + - [For database migration, refer to this document first](previous_version_upgrade/mariadb-mysql.md){:target="_blank"} + - [For versions smaller than 1.4.4 before upgrade, follow this document](previous_version_upgrade/1.0.0-1.4.3.md){:target="_blank"} + - [For versions smaller than 1.4.5 before upgrade, follow this document](previous_version_upgrade/1.4.4.md){:target="_blank"} + - [For users not using installer deployment, refer to migration instructions to migrate to the latest version](migration.md){:target="_blank"} + +!!! tip "Environment Description" + - Starting from v2.5, MySQL Server >= 5.7 is required + - Starting from v2.6, Redis Server >= 6.0 is required + - It is recommended to use external DB Server and Redis Server for convenient expansion and upgrade + +!!! tip "External Database Requirements" + + | Component | Version | + | --- | --- | + | MySQL | >= 5.7 | + | MariaDB | >= 10.3 | + | Redis | >= 6.0 | diff --git a/docs/manual/admin/audit/session_audit/file_transfer.en.md b/docs/manual/admin/audit/session_audit/file_transfer.en.md new file mode 100644 index 000000000..d00c425f7 --- /dev/null +++ b/docs/manual/admin/audit/session_audit/file_transfer.en.md @@ -0,0 +1,9 @@ +# File Transfer + +## 1 Feature Overview + +!!! tip "" + - Click the **Audit** button on the navigation bar to open the **Audit** page. + - Click **Session Audit > File Transfer** to open the **File Transfer** page. + - File transfer allows you to view the history of all files uploaded to/downloaded from assets. +![file_transfer_01](../../../../img/v4_file_transfer_01.png) diff --git a/docs/manual/admin/audit/session_audit/job_audit/job_list.en.md b/docs/manual/admin/audit/session_audit/job_audit/job_list.en.md new file mode 100644 index 000000000..ce4ad0356 --- /dev/null +++ b/docs/manual/admin/audit/session_audit/job_audit/job_list.en.md @@ -0,0 +1,10 @@ +# Job List + +## 1 Feature Overview + +!!! tip "" + - Click the **Audit** button on the navigation bar to open the **Audit** page. + - Click **Job Audit > Job List** to open the **Job List** page. + - Reviewers can view all job information created by users on this page. + +![job_list_01](../../../../../img/v4_job_list_01.png) diff --git a/docs/manual/admin/audit/session_audit/job_audit/job_logs.en.md b/docs/manual/admin/audit/session_audit/job_audit/job_logs.en.md new file mode 100644 index 000000000..cb48bb9ff --- /dev/null +++ b/docs/manual/admin/audit/session_audit/job_audit/job_logs.en.md @@ -0,0 +1,15 @@ +# Job Logs + +## 1 Feature Overview + +!!! tip "" + - Click the **Audit** button on the navigation bar to open the **Audit** page. + - Click **Job Audit > Job Logs** to open the **Job Logs** page. + - Job tasks are log information records of task execution in the user's job center functionality. + - Main recorded information includes task creator, execution command, whether completed/successful, date, and other information, and can output execution task records. + +![job_logs_01](../../../../../img/v4_job_logs_01.png) + +!!! tip "" + - Task log output example is shown below: +![job_logs_02](../../../../../img/v4_job_logs_02.png) diff --git a/docs/manual/admin/audit/session_audit/log_audit/login_logs.en.md b/docs/manual/admin/audit/session_audit/log_audit/login_logs.en.md new file mode 100644 index 000000000..ac49cd4c6 --- /dev/null +++ b/docs/manual/admin/audit/session_audit/log_audit/login_logs.en.md @@ -0,0 +1,9 @@ +# Login Logs + +## 1 Feature Overview + +!!! tip "" + - Click the **Audit** button on the navigation bar to open the **Audit** page. + - Click **Log Audit > Login Logs** to open the **Login Logs** page. + - Login logs refer to user login logs of the JumpServer platform. On this page you can view detailed information about user logins to JumpServer including login type, login IP, login city, login date, login failure reasons, and other information. +![login_logs_01](../../../../../img/v4_login_logs_01.png) diff --git a/docs/manual/admin/audit/session_audit/log_audit/operation_logs.en.md b/docs/manual/admin/audit/session_audit/log_audit/operation_logs.en.md new file mode 100644 index 000000000..7f2d46fc4 --- /dev/null +++ b/docs/manual/admin/audit/session_audit/log_audit/operation_logs.en.md @@ -0,0 +1,14 @@ +# Operation Logs + +## 1 Feature Overview + +!!! tip "" + - Click the **Audit** button on the navigation bar to open the **Audit** page. + - Click **Log Audit > Operation Logs** to open the **Operation Logs** page. + - Operation logs refer to management operation logs of the entire JumpServer platform. On this page you can view the user performing the operation, resource type, operation logs, and other information. + - Specific operation changes can be viewed by clicking the **View** button after the operation log. +![operation_logs_01](../../../../../img/v4_operation_logs_01.png) + +!!! tip "" + - Auditors can view detailed changes of operation logs through the **View** button. +![operation_logs_02](../../../../../img/v4_operation_logs_02.png) diff --git a/docs/manual/admin/audit/session_audit/log_audit/password_change_logs.en.md b/docs/manual/admin/audit/session_audit/log_audit/password_change_logs.en.md new file mode 100644 index 000000000..422c0764a --- /dev/null +++ b/docs/manual/admin/audit/session_audit/log_audit/password_change_logs.en.md @@ -0,0 +1,10 @@ +# Password Change Logs + +## 1 Feature Overview + +!!! tip "" + - Click the **Audit** button on the navigation bar to open the **Audit** page. + - Click **Log Audit > Password Change Logs** to open the **Password Change Logs** page. + - Password change logs are for JumpServer platform user password changes, i.e., JumpServer user account password changes. + - Main recorded information includes password change user, modifier, date, and other information. +![password_change_logs_01](../../../../../img/v4_password_change_log_01.png) diff --git a/docs/manual/admin/audit/session_audit/online_user.en.md b/docs/manual/admin/audit/session_audit/online_user.en.md new file mode 100644 index 000000000..83465a8d2 --- /dev/null +++ b/docs/manual/admin/audit/session_audit/online_user.en.md @@ -0,0 +1,9 @@ +# Online Users + +## 1 Feature Overview + +!!! tip "" + - Click the **Audit** button on the navigation bar to open the **Audit** page. + - Click **Session Audit > Online Users** to open the **Online Users** page. + - Through the **Online Users** page, you can view information about users currently logged in to JumpServer (currently limited to web login users), and control user logout from this page. Administrators or auditors can view logged-in users through the online users device feature. +![online_user_01](../../../../img/v4_online_user_01.png) diff --git a/docs/manual/admin/audit/session_audit/reports.en.md b/docs/manual/admin/audit/session_audit/reports.en.md new file mode 100644 index 000000000..ce3a2724e --- /dev/null +++ b/docs/manual/admin/audit/session_audit/reports.en.md @@ -0,0 +1,25 @@ +# Reports + +!!! tip "" + - Click the **Audit** button on the navigation bar to open the **Audit** page. + - Click **Session Audit > Reports** to open the **Reports** page. + - On the reports page you can view user login reports, user password change reports, asset statistics reports, asset activity reports, account statistics reports, account automation reports, supporting visual data analysis and export. + +## 1 User Reports + +!!! tip "" + - On the user reports page you can view user login reports / user password change reports. You can view by today, last 7 days, last 30 days +![report1](../../../../img/reports1.png) + +## 2 Asset Reports + +!!! tip "" + - On the asset reports page you can view asset statistics reports / asset activity reports. Asset activity reports can be viewed by today, last 7 days, last 30 days + +![report2](../../../../img/reports2.png) + +## 3 Account Reports + +!!! tip "" + - On the account reports page you can view account statistics reports / account automation reports. Account automation reports can be viewed by today, last 7 days, last 30 days +![report3](../../../../img/reports3.png) diff --git a/docs/manual/admin/audit/session_audit/session_command.en.md b/docs/manual/admin/audit/session_audit/session_command.en.md new file mode 100644 index 000000000..9717ee37c --- /dev/null +++ b/docs/manual/admin/audit/session_audit/session_command.en.md @@ -0,0 +1,15 @@ +# Session Commands + +## 1 Feature Overview + +!!! tip "" + - Click the **Audit** button on the navigation bar to open the **Audit** page. + - Click **Session Audit > Session Commands** to open the **Session Commands** page. + - Session commands mainly display commands executed by users after asset connection. By clicking a specific record row, you can view detailed command execution results. + - Click to switch to the **Session** commands page. Click the dropdown box shown to display partial output of command execution results. +![session_command_02](../../../../img/v4_session_command_02.png) + +!!! tip "" + - Click the **Session** link to jump to the detailed session page. If the session has ended, you can view the session recording. +![session_command_03](../../../../img/v4_session_command_03.png) +![session_command_04](../../../../img/v4_session_command_04.png) diff --git a/docs/manual/admin/audit/session_audit/session_record.en.md b/docs/manual/admin/audit/session_audit/session_record.en.md new file mode 100644 index 000000000..d00e65d11 --- /dev/null +++ b/docs/manual/admin/audit/session_audit/session_record.en.md @@ -0,0 +1,45 @@ +# Session Records + +## 1 Feature Overview + +!!! tip "" + - Click the **Audit** button on the navigation bar to open the **Audit** page. + - Click **Session Audit > Session Records** to open the **Session Records** page. + - Session records contain online sessions and historical sessions in two parts, mainly displaying detailed session records of asset logins, including user, protocol, remote address, session time, and session recordings. + +## 2 Online Sessions + +!!! tip "" + - Online sessions allow you to view all currently active sessions of users logging into assets through JumpServer. Real-time monitoring is supported, and sessions can be terminated directly when non-compliant operations occur. + - JumpServer real-time monitoring supports SSH and RDP protocol session connections. RDP client method sessions and database protocol sessions currently do not support real-time monitoring. + +!!! tip "" + - Click to switch to the **Session Records - Online Sessions** tab as shown: +![session_record_01](../../../../img/v4_session_record_01.png) + +## 3 Historical Sessions + +!!! tip "" + - Historical sessions allow you to view detailed information and operation recordings of all JumpServer asset connections, facilitating review and accountability. + - JumpServer allows viewing recordings online in the browser or downloading recordings to local and playing them through JumpServer's offline recording player. + +!!! tip "" + - Click to switch to the **Session Records - Historical Sessions** tab as shown: +![session_record_02](../../../../img/v4_session_record_02.png) + +### 3.1 Session Details + +!!! tip "" + - Click the **Session Records - Historical Sessions** tab, then click the **Serial Number** button on this page to enter the session details page. +![session_record_03](../../../../img/v4_session_record_03.png) + +!!! tip "" + - Detailed module descriptions: + +| Module | Description | +| --- | --- | +| Basic Information | Basic information module mainly introduces the basic information of this session, including login user, login source, remote address, session start time and end time, etc. | +| Commands | Command module can query command records executed by the user during this session connection. | +| Collaboration Records | Collaboration records can query the record contents of session sharing during this session connection. | +| File Transfer | File transfer module can query files uploaded and downloaded during this session connection. | +| Activities | Displays the latest specific session connection activity record contents. | diff --git a/docs/manual/admin/audit/session_audit/ticket_audit.en.md b/docs/manual/admin/audit/session_audit/ticket_audit.en.md new file mode 100644 index 000000000..0dc1b94a6 --- /dev/null +++ b/docs/manual/admin/audit/session_audit/ticket_audit.en.md @@ -0,0 +1,14 @@ +# Ticket List + +!!! tip "" + - Click the **Audit** button on the navigation bar to open the **Audit** page. + - Click **Session Audit > Ticket List** to open the **Ticket List** page. + - The ticket list page displays the list of tickets submitted by system users. Click on the corresponding ticket title to view ticket details. + +![image](../../../../img/ticket_audit01.png) + +**Ticket Details** + +!!! tip "" + - The ticket details page displays detailed ticket information, including ticket title, ticket content, ticket status, ticket handler, ticket creation time, etc. +![image](../../../../img/ticket_audit02.png) diff --git a/docs/manual/admin/console/access_control/acls.en.md b/docs/manual/admin/console/access_control/acls.en.md new file mode 100644 index 000000000..2eed5946a --- /dev/null +++ b/docs/manual/admin/console/access_control/acls.en.md @@ -0,0 +1,143 @@ +# Access Control + +## 1 Command Filtering +### 1.1 Overview +!!! tip "" + - Go to the Console page, click **Account Management > Account List** to open the account list page. + - JumpServer supports filtering commands used during session processes and setting command filtering rules. + - Command filters can be bound to JumpServer users, assets, and accounts used to connect to assets. One command filter can be bound to multiple command groups. When a bound user uses a bound account to connect to a bound asset and execute commands, the command must be matched by all command groups bound to the filter. Higher priority rules are matched first. When a matching rule is found, the action specified by that rule is executed. If no matching rule is found, the command executes normally. + +### 1.2 Create command filter +!!! tip "" + - This page allows creating, deleting, updating, and viewing command filters. + - Click the **Command Filter** tab on the **Command Filtering** page to open the command filter page. + - Click the **Create** button in the top-left corner to create a command filter. +![V4_commandfilter_1](../../../../img/V4_commandfilter_1.png) + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | +|-----------|-------------| +| Name | The name of the command filter | +| Users | • **All users**: All user resources
    • **Specified users**: Specified user resources
    • **Property filter**: Filter target resources by matching property values | +| Assets | • **All assets**: All asset resources
    • **Specified assets**: Specified asset resources
    • **Property filter**: Filter target resources by matching property values | +| Account | • **All accounts**: All account resources
    • **Specified accounts**: Specified account resources | +| Command Groups | The command groups associated with this command filter. When a matching user executes these commands using a matching account on a matching asset, the corresponding action is executed | +| Action | • **Deny**: Deny asset login
    • **Accept**: Allow asset login
    • **Review**: Approval personnel receive a command review notification and can allow or deny the corresponding action
    • **Alert**: Send alert information to designated personnel when a matching command is detected | +| Priority | The priority of the command filter, priority range 1~100, lower values have higher priority, default 50 | + +### 1.3 Create command group +!!! tip "" + - Command groups can be bound to command filters. Command groups currently support two types of syntax: regular expressions and commands. + - Click the **Command Groups** tab on the **Command Filtering** page to open the command group page. + - Click the **Create** button in the top-left corner to create a command group. +![V4_commandfilter_2](../../../../img/V4_commandfilter_2.png) + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | +|-----------|-------------| +| Name | The name of the command group | +| Type | Regular expression means matching commands through regular expressions; command means filtering specific commands | +| Content | Content can be multi-line text; each line represents a matching rule | +| Ignore Case | Fill in the command regardless of case; filter according to rules | + +## 2 User login +!!! warning "Note: User login review is a JumpServer Enterprise edition feature." +### 2.1 Overview +!!! tip "" + - JumpServer supports secondary review functionality for user login. + - Based on security policies, the system can restrict user login based on JumpServer login user attributes. When secondary review action is set, approval personnel review the user login. + +### 2.2 Create user login rule +!!! tip "" + - Click the **Create** button on the **Access Control - User Login** page and fill in the user login rule information. +![user_login_01](../../../../img/v4_user_login_01.png) + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | +|-----------|-------------| +| Name | The name of the user login rule | +| Priority | The priority of the user login rule, priority range 1~100, lower values have higher priority, default 50 | +| Users | Specify the users matched by the login rule
    All users: The login rule matches all users
    Specified users: The login rule matches specified users
    Property filter: The login rule matches users matched by property rules | +| IP Group | Specify the login IP restricted by the login rule, format is a comma-separated string, `*` matches all. Examples: 192.168.10.1, 192.168.1.0/24, 10.1.1.1-10.1.1.20, 2001:db8:2de::e13, 2001:db8:1a:1110::/64. This IP is the user's login IP | +| Time Window | Specify the time period restricted by the login rule | +| Action | Specify the action when the login rule is executed:
    • Deny: When a user login matches the above rule, deny the user login
    • Accept: When a user login matches the above rule, accept the user login
    • Review (X-Pack): When a user login matches the above rule, send a ticket to approval personnel for approval before allowing login
    • Notify: When a user login matches the above rule, send notification to specified users | +| Enabled | Specify whether the login rule is active | + +## 3 Asset connection (X-Pack) +!!! info "Note: Asset connection review is a JumpServer Enterprise edition feature." +### 3.1 Overview +!!! tip "" + - JumpServer supports secondary review functionality for asset connections. + - Based on security policies, the system can restrict asset connections based on three dimensions: JumpServer login user, asset information, and account information. When secondary review action is set, approval personnel review the asset connection. +### 3.2 Create asset connection rule +!!! tip "" + - Click the **Create** button on the **Access Control - Asset Connection** page and fill in the asset connection rule information. +![V4_assets_connect_1](../../../../img/V4_assets_connect_1.png) + +!!! tip "" + - Detailed parameter descriptions: + + | Parameter | Description | + |-----------|-------------| + | Name | The name of the asset connection rule | + | Priority | The priority of the asset connection rule, priority range 1~100, lower values have higher priority, default 50 | + | Users | • **All users**: All user resources
    • **Specified users**: Specified user resources
    • **Property filter**: Filter target resources by matching property values | + | Assets | • **All assets**: All asset resources
    • **Specified assets**: Specified asset resources
    • **Property filter**: Filter target resources by matching property values | + | Account | • **All accounts**: All account resources
    • **Specified accounts**: Specified account resources | + | Login IP | Restrict the IP address for asset connection | + | Time Window | Restrict the time period for asset connection | + | Action | • **Deny**: Deny asset connection
    • **Accept**: Allow asset connection
    • **Review**: Allow or deny connection after approval by designated approvers
    • **Notify**: Send notification to designated recipients when rule is triggered
    • **Password rotation**: Automatically execute asset account password change after login

    **Note**: Enabling **Password rotation** requires adding the parameter `CHANGE_SECRET_AFTER_SESSION_END=true` to the configuration file and restarting JumpServer | + +## 4 Data masking (X-Pack) +!!! info "Note: Query result data masking is a JumpServer Enterprise edition feature." +> Client-based connections (Magnus component) for databases other than MySQL are currently not supported for data masking. +### 4.1 Feature overview +!!! tip "" + - JumpServer supports data masking for query results when connecting to database assets. + - Through data masking rules, you can set sensitive data to be masked for users when they get query results (globally effective). + +### 4.2 Create data masking rule +!!! tip "" + - Click the **Create** button on the **Permission Management > Data Masking** page and fill in the data masking rule information. +![V4_data_desensitive_1](../../../../img/V4_data_desensitive_1.png) + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | +|-----------|-------------| +| Name | The name of the data masking rule | +| Priority | The priority of the data masking rule, priority range 1~100, lower values have higher priority, default 50 | +| Users | • **All users**: All user resources
    • **Specified users**: Specified user resources
    • **Property filter**: Filter target resources by matching property values | +| Assets | • **All assets**: All asset resources
    • **Specified assets**: Specified asset resources
    • **Property filter**: Filter target resources by matching property values | +| Account | • **All accounts**: All account resources
    • **Specified accounts**: Specified account resources | +| Rules | • **Mask column names**: Support multiple field names, comma-separated, supports wildcards. For example:
    Single field name `password` means only mask `password` field
    Multiple field names: `password,secret` means mask `password` and `secret`
    Wildcard `*`: `password*` means mask field names with `password` prefix
    Wildcard `*`: `.*password` means mask field names with `password` suffix
    • **Mask method**: Mask data according to the selected method | + +## 5 Connection method (X-Pack) +!!! info "Note: Connection method control is a JumpServer Enterprise edition feature." +### 5.1 Feature overview +!!! tip "" + - JumpServer supports controlling connection methods when connecting to assets. + - Through connection method filtering, you can control whether users can use a certain connection method to log in to assets. Based on your rules, some connection methods can be allowed while others are prohibited (globally effective). + +### 5.2 Create connection method control rule +!!! tip "" + - Click the **Create** button on the **Permission Management > Connection Method** page and fill in the connection method control rule information. +![V4_connect_type_1](../../../../img/V4_connect_type_1.png) + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | +|-----------|-------------| +| Name | The name of the connection method control rule | +| Priority | The priority of the connection method control rule, priority range 1~100, lower values have higher priority, default 50 | +| Users | • **All users**: All user resources
    • **Specified users**: Specified user resources
    • **Property filter**: Filter target resources by matching property values | +| Connection Method | Asset connection methods provided by JumpServer, common ones include: Web CLI, Web SFTP, SSH, Web GUI, database client, etc. | +| Action | The action when a connection method control rule is matched:
    • **Deny**: Deny use of the connection method restricted in the rule | diff --git a/docs/manual/admin/console/account_management/account_list.en.md b/docs/manual/admin/console/account_management/account_list.en.md new file mode 100644 index 000000000..2aa00bb21 --- /dev/null +++ b/docs/manual/admin/console/account_management/account_list.en.md @@ -0,0 +1,31 @@ +# Account List +## 1 Overview +!!! tip "" + - Go to the Console page, click **Account Management > Account List** to open the account list page. + - JumpServer supports managed account management for assets. + +## 2 Features +### 2.1 View account information +!!! tip "" + - Click the asset tree or type tree on the left side of the page to select a node or asset to view the account information associated with the asset (by default, admin MFA verification is required) +![account_list_01](../../../../img/v4_account_list_01.png) +!!! tip "Hint" + - MFA verification is required to view detailed account information such as account passwords. + - For security, JumpServer defaults to requiring MFA verification to view passwords. To disable MFA verification, add the configuration `SECURITY_VIEW_AUTH_NEED_MFA=False` to the JumpServer configuration file (default: `/opt/jumpserver/config/config.txt`) and restart the JumpServer service. +### 2.2 Account information import/export +!!! tip "" + - You can bulk export account information. JumpServer supports exporting detailed information and passwords of all accounts associated with assets. Account filtering can quickly filter the account list based on account type and risk accounts. +![account_list_02](../../../../img/v4_account_list_02.png) +### 2.3 Add account +!!! tip "" + - JumpServer supports bulk associating one account with multiple assets (account adding feature). Click the **Add** button on the account list page, select the assets to associate with the account, fill in the account details, and bulk associate the account with the assets. +![account_list_03](../../../../img/v4_account_list_03.png) +### 2.4 Add account template +!!! tip "" + - Click the **Template Add** button on the account list page, select the assets to associate the account template with, choose the account template to add, and bulk associate the account template with the assets. +![account_list_04](../../../../img/v4_account_list_04.png) + +## 3 Virtual accounts +!!! tip "" + - In certain scenarios during authorization rule creation, virtual accounts are used to log in to assets. The virtual account page supports viewing details of virtual accounts. JumpServer supports allowing AD/LDAP users to log in to assets with JumpServer user passwords when authorization rules authorize accounts with the same name. +![account_list_05](../../../../img/v4_account_list_05.png) diff --git a/docs/manual/admin/console/account_management/account_template.en.md b/docs/manual/admin/console/account_management/account_template.en.md new file mode 100644 index 000000000..cee0cdf1d --- /dev/null +++ b/docs/manual/admin/console/account_management/account_template.en.md @@ -0,0 +1,10 @@ +# Account Template +## 1 Overview +!!! tip "" + - Go to the Console page, click **Account Management > Account Templates** to open the account template page. + - In managed assets, it is common for multiple asset accounts to have the same username and password. The account template feature simplifies the account creation step when creating assets. During authorization, select an account template, which represents an account information. + +## 2 Create account template +!!! tip "" + - Click the **Create** button on the account template page to open the account template creation page. +![account_template_01](../../../../img/v4_account_template_01.png) diff --git a/docs/manual/admin/console/assets/assets_list.en.md b/docs/manual/admin/console/assets/assets_list.en.md new file mode 100644 index 000000000..ca22b5ae4 --- /dev/null +++ b/docs/manual/admin/console/assets/assets_list.en.md @@ -0,0 +1,156 @@ +# Asset List + +## 1 Overview +!!! tip "" + - Click the **Console** button on the navigation bar to open the **Console** page. + - Click **Asset Management > Asset List** to open the **Asset List** page. + - The asset list page includes asset tree and type tree, asset types, asset creation, asset updates, asset details, asset deletion and other functional modules. + +## 2 Asset tree and type tree +### 2.1 Asset tree +!!! tip "" + - The asset tree displays all assets in a hierarchical structure organized by nodes. + - Asset tree root nodes cannot have duplicate names. Right-click on a node to add, delete, and rename nodes, as well as perform asset-related operations. + +![V4_assets_build_1](../../../../img/V4_assets_tree_1.png) + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | +|-----------|-------------| +| Create Node | Create a new child node under the current node | +| Rename Node | Rename the node | +| Delete Node | Delete the current node | +| Add Assets to Node | Add assets from other nodes to the current node; assets in the original node are not removed | +| Move Assets to Node | Move assets from other nodes to the current node; assets in the original node are removed | +| Update Node Asset Hardware Info | Start an automation task to batch update hardware information for assets under the current node. Note: Assets under the current node must have automation tasks enabled with correctly configured privileged users; this feature only supports SSH protocol. | +| Test Asset Node Connectivity | Start an automation task to batch test the connectivity of assets under the current node. Note: Assets under the current node must have automation tasks enabled with correctly configured privileged users; this feature only supports SSH protocol. | +| Show Current Node Assets Only | Only display assets under the current node, excluding assets in child nodes | +| Show All Child Node Assets | Display assets in the current node and all child nodes, regardless of multi-level nesting | +| Verify Asset Count | Verify the asset count under the current node | +| Show Node Details | Display detailed information about the current node, including node ID, name, and full path | + +### 2.2 Type tree +!!! tip "" + - The type tree is another way to categorize assets. JumpServer organizes hosts, network devices, databases, and other resources as assets. The type tree mainly displays the count of each asset type for a more intuitive view of asset distribution. + +![V4_assets_build_2](../../../../img/V4_assets_tree_2.png) + +## 3 Asset types +!!! info "Note: Oracle, SQL Server, ClickHouse, Dameng, DB2 databases are JumpServer Enterprise edition features." +!!! tip "" + - JumpServer categorizes hosts, network devices, databases, and other resources as assets. + - Host types default to include Linux, Windows, and Unix assets. +![alt text](../../../../img/V4_assets_type_3.png) + +!!! tip "" + - Network device types default to include General, Cisco, Huawei, and H3C. +![V4_assets_build_4](../../../../img/V4_assets_type_4.png) + +!!! tip "" + - Database types default to include MySQL, MariaDB, PostgreSQL, Redis, MongoDB, Oracle, SQL Server, ClickHouse, Dameng, and DB2. + - Some databases support TLS encrypted connections through koko, such as MySQL, SQL Server, etc. +![V4_assets_build_5](../../../../img/V4_assets_type_5.png) + +!!! tip "" + - Cloud services default to include private cloud VMs and Kubernetes. +![V4_assets_build_6](../../../../img/V4_assets_type_6.png) + +!!! tip "" + - Web type assets include website resources. For detailed Web asset configuration, see [Creating Web Assets](web_assets.md). +![V4_assets_build_7](../../../../img/V4_assets_type_7.png) + +!!! tip "" + - Directory Service is used for centralized storage, management, and querying of network resource information. Common implementations include LDAP and Active Directory. +![V4_assets_type_8](../../../../img/V4_assets_type_8.png) + +!!! tip "" + - In addition to built-in asset types, JumpServer supports custom asset types through remote applications, such as test software, note-taking software, etc. +![V4_assets_type_9](../../../../img/V4_assets_type_9.png) + +## 4 Asset creation +### 4.1 Manually create a single asset + +!!! tip "" + - JumpServer supports manual asset creation. Asset creation requires filling in basic information such as asset name, IP address, accounts, node information, etc. + - Click the **Create** button in the top-left corner of the page and select a Linux asset to open the asset creation page, then fill in the asset details. +![V4_assets_build_8](../../../../img/V4_assets_build_8.png) +!!! tip "" + - Detailed parameter descriptions: + +| Parameter | Description | +|-----------|-------------| +| Name | Required. The asset name in JumpServer, unrelated to the computer name; must be unique | +| IP/Hostname | Required. The real address of the asset, supporting domain names and IP addresses. Duplicates are allowed. | +| Asset Platform | Default parameter. The asset platform; different platforms can set different character encodings, connection parameters, and password change commands | +| Node | Required. The node to which the asset belongs | +| Protocol Group | Required. Protocols used to access the asset; one or more protocols can be selected | +| Account List | Optional. Accounts used to log in to the asset; multiple accounts can be created. Accounts are bound to assets. | +| Domain | Optional. For assets across network segments, access through a domain gateway as a proxy is required | +| Label | Optional. Add labels to the asset for easier management | +| Active | Required. Whether the asset is available for use | + +### 4.2 Bulk import assets via Excel +!!! tip "" + - JumpServer supports bulk asset creation and updates through Excel import. + - For the first import, click the Import button in the top-right corner of the asset list, download the template, fill in the information to create or update, then import the file. +![V4_assets_build_9](../../../../img/V4_assets_build_9.png) + +### 4.3 Cloud sync (x-pack) +!!! info "Note: Cloud sync is a JumpServer Enterprise edition feature." +!!! tip "" + - JumpServer supports cloud host synchronization. Currently supported cloud platforms include: Alibaba Cloud, Tencent Cloud, Huawei Cloud, Baidu Cloud, JD Cloud, Kingsoft Cloud, AWS, Azure, Google Cloud, UCloud, VMware, QingCloud, China Telecom Cloud, OpenStack, ZStack, Nutanix, Fusion Compute, Shenzhen Xinfengfu Cloud Platform, Alibaba Cloud Private Cloud, and LAN. + - Click the Account List tab on the cloud sync page to create cloud accounts. + +![V4_assets_build_10](../../../../img/V4_assets_build_10.png) + +!!! tip "" + - Then fill in the cloud account. Using Tencent Cloud as an example (obtain Tencent Cloud keys from the Tencent Cloud account page): + +![V4_assets_build_11](../../../../img/V4_assets_build_11.png) + +!!! tip "" + - After successfully creating a cloud account, it will appear on the cloud provider page. JumpServer admins can create multiple cloud account types to synchronize cloud hosts. + - Select `Online Sync` to synchronize cloud resources on the page. + +![V4_assets_build_12](../../../../img/V4_assets_build_12.png) + +!!! tip "" + - Start the sync and wait for the task to complete, select hosts, and click to import. + - Check the import results in the asset list. If the imported assets are found in the asset list, the cloud account asset synchronization is working normally. + +!!! info "Cloud sync task auto-release behavior (feature in v4.10.4 and later)" + - After enabling "Cloud sync task auto-release", if the first sync selected regions A and B, and later modifications keep only region A, the system will not automatically release assets previously synced from region B on the next sync (older versions would). + - To offload assets from removed regions, manually execute release or configure cleanup logic in policies separately to avoid accidentally deleting resources still in use. + +![V4_assets_build_15](../../../../img/V4_assets_build_15.png) + +!!! tip "" + - If users need to establish specific sync rules during the cloud sync process, they can define sync policies. The steps to create a sync policy are as follows: + - Fill in the information and click `Submit` at the bottom to create the policy. +![V4_assets_build_16](../../../../img/V4_assets_build_16.png) + +!!! tip "" + - Detailed parameter descriptions: + +| Parameter | Description | +|-----------|-------------| +| Name | The name of the cloud sync policy | +| Priority | The priority of the sync policy. 1-100, lower numbers have higher priority | +| Condition Relationship | AND: Execute the action only when all conditions match. OR: Execute the action when at least one condition matches | +| Condition | Policy rules used to match assets on cloud platforms. For example, instance name, platform name, and address | +| Action Settings | Policy actions executed on JumpServer after successfully matching assets. It can set platforms, nodes, regions, and account templates for successfully synced assets | + + +## 5 Update assets +!!! tip "" + - When you need to update an asset's information, click the **Update** button next to the asset to open the asset information update page and update the asset details. + +![V4_assets_update_13](../../../../img/V4_assets_update_13.png) + +## 6 Asset details +!!! tip "" + - Click the asset name to open the asset detail page, which displays detailed information including basic info, accounts, authorization rules, activity logs, etc. + +![V4_assets_finduser_1](../../../../img/V4_assets_finduser_1.png) diff --git a/docs/manual/admin/console/assets/net_list.en.md b/docs/manual/admin/console/assets/net_list.en.md new file mode 100644 index 000000000..62733e260 --- /dev/null +++ b/docs/manual/admin/console/assets/net_list.en.md @@ -0,0 +1,73 @@ +# Domain List +## 1 Overview +!!! tip "" + - Go to the **Console** page, click **Asset Management > Domain List** to open the domain list page. + - JumpServer supports the domain feature, which is designed to solve network connectivity issues between JumpServer and certain assets. The principle is to use a gateway server to establish an SSH tunnel for traffic forwarding. + +## 2 Create a domain +!!! tip "" + - Click the **Create** button on the **Domain List** page to open the domain information settings page and fill in the domain details. + +![V4_net_creat_1.png](../../../../img/V4_net_creat_1.png) + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | +|-----------|-------------| +| Name | The domain identification name | +| Assets | The assets that need to use the domain to communicate with JumpServer | + +## 3 Domain details + +!!! tip "" + - Click the **Domain Name** button on the **Domain List** page to open the **Domain Detail** page, which contains the domain details, gateway list, asset list, and activity logs. + +![V4_net_detail_2.png](../../../../img/V4_net_detail_2.png) + +!!! tip "" + - Basic Settings: This module contains detailed information about the domain, such as its name and creation date. + - Gateway List: This module is used to add, delete, update, and query gateways. + - Asset List: Displays the asset list within the domain. + - Activity: This module mainly records activity logs for the domain. + +## 4 Create a gateway + +!!! tip "" + - On the **Domain Detail** page, click the **Gateway List** tab to create gateway address information for the domain. JumpServer will use the gateway server to establish an SSH tunnel and connect to assets. After creation, you can update, copy, and test gateway connectivity. + +![V4_gateway_create_3](../../../../img/V4_gateway_create_3.png) + +![V4_gateway_create_4](../../../../img/V4_gateway_create_4.png) + +## 5 Update domain + +!!! tip "" + - When you need to update a domain's information, click the **Edit** button next to the domain to open the **Domain Update** page and update the domain details. When you need to modify the gateway information for the domain, click the **Domain Name** button to open the **Domain Detail** page and update the gateway information in the **Gateway List** section. + +![V4_net_update_5](../../../../img/V4_net_update_5.png) + +## 6 Delete domain + +!!! tip "" + - When you need to delete a domain, click the **Edit** button next to the domain and select **Delete**. + +![V4_net_delete_2](../../../../img/V4_net_delete_2.png) + +## 7 Clone domain + +!!! tip "" + - To copy a specific domain, click the **More** button next to the corresponding domain and select **Copy**. + +![V4_net_detail_1](../../../../img/V4_net_clone_1.png) + +## 8 Test connection + +!!! tip "" + - To test the connectivity of a gateway, click the **More** button next to the corresponding domain and select **Test Connection**. + +![V4_net_test_5](../../../../img/V4_net_test_5.png) + +!!! tip "" + - Then select the port for which you want to test connectivity. +![V4_net_test_1](../../../../img/V4_net_test_1.png) diff --git a/docs/manual/admin/console/assets/web_assets.en.md b/docs/manual/admin/console/assets/web_assets.en.md new file mode 100644 index 000000000..a531919cd --- /dev/null +++ b/docs/manual/admin/console/assets/web_assets.en.md @@ -0,0 +1,125 @@ +# Web Assets +## 1 Overview +!!! tip "" + - Web assets are a type of resource supported by JumpServer, designed to access web systems through remote applications. They are suitable for centralized management of internal systems, SaaS services, or other web-based applications. + - Web assets depend on remote application publishers, which can be deployed on Windows or Linux systems. + - When a user connects to a web asset, the system automatically invokes the publisher to launch a preconfigured browser for accessing the target system. This approach enables secure and controlled access, effectively preventing users from directly accessing the target address. + + +## 2 Create a web asset + +!!! warning "" + Before using Web-type assets, you must configure a remote application publisher. See [Remote Applications](../../system_settings/remote_apps.md) for detailed configuration. + +!!! tip "" + - Go to the **Console** page, click **Asset Management > Asset List** to open the asset list page. + - Click the **Create** button in the top-left corner of the page, select **Web** type asset to open the asset creation page, and fill in the asset details. + +!!! tip "" + - Detailed parameter descriptions: + +| Parameter | Description | +|-----------|-------------| +| Name | Required. The asset name in JumpServer, unrelated to the computer name; must be unique | +| IP/Hostname | Required. The real address of the web page, supporting domain names and IP addresses. Duplicates are allowed. If the port is not 80 or 443, include the port number. | +| Asset Platform | Default. The asset platform for Web-type assets | +| Node | Required. The node to which the asset belongs | +| Selector | Required. Select the auto-fill mode. See [Auto-fill](#3) in this document for detailed configuration | +| Protocol | Default. Default HTTP/HTTPS protocol | +| Account List | Optional. Accounts used to log in to the asset; multiple accounts can be created. Accounts are bound to assets. | +| Domain | Optional. For assets across network segments, access through a network gateway as a proxy is required. **Web assets do not support gateways by default; this option only serves to annotate gateway machine information** | +| Label | Optional. Add labels to the asset for easier management. Web assets also support specifying specific remote app publishers through labels. | +| Active | Required. Whether the asset is available for use | +| Note | Optional. Description of the asset information | + +## 3 Auto-fill + +!!! tip "" + - The auto-fill feature is mainly used for websites that require user authentication. Before users access such websites, JumpServer automatically fills in predefined usernames and passwords on the login page to complete authentication. This process is transparent to users without requiring manual credential entry. + +### 3.1 Disable auto-fill + +!!! tip "" + - This method applies to websites that do not require authentication. + +### 3.2 Basic auto-fill + +!!! tip "" + - This method applies to websites where the username, password, and login button are all on the same page. JumpServer automatically fills in the credentials and submits the form to authenticate the user. + + - When filling in information automatically, **you need to locate elements on the web page**. Supported selector types include name selectors, ID selectors, class selectors, CSS selectors, and XPath selectors. For more information, see [Selenium Python: Locating Elements](https://selenium-python.readthedocs.io/locating-elements.html). + +### 3.3 Script auto-fill +!!! tip "" + - This script method applies to websites with complex login procedures. It supports advanced automation, including multi-step authentication and interaction with dynamic page elements. + +### 3.3.1 Script structure +!!! tip "" + - The script is an array where each element is a dictionary representing a step in the script. + + - Syntax explanation: + +| Step | Description | +| :------ | :----------------------------------------------------------- | +| step | Required.
    Integer.
    Indicates the execution order of the script, starting from 1 and incrementing | +| value | Required.
    String.
    Supported built-in variables: {USERNAME}, {SECRET}.
    If the command is not of type, leave the value empty | +| target | Required.
    String.
    The target element to act on, can be a selector or XPath expression | +| command | Required.
    String.
    The command to execute, can be one of: click, type, sleep, select_frame | + +| Action | Description | +| :----------- | :----------------------------------------------------------- | +| click | Click the target element | +| type | Type the value in the target element | +| sleep | Pause the script for a specified duration, usually to allow page loading during navigation. Duration is specified by the target, in seconds | +| select_frame | Switch to the specified iframe for action.
    Target supports options like id=iframe_id, name=iframe_name, or index=1 (if index < 0, switch back to the default/main iframe) | + +### 3.3.2 Script example + +```json +[ + // Switch to the iframe with id=iframe_id. + { + "step": 1, + "command": "select_frame", + "target": "id=iframe_id", + "value": "" + }, + // Type username in the input field name=username. + // When the script is executed, the {USERNAME} variable will be replaced with the actual username. + { + "step": 2, + "command": "type", + "target": "name=username", + "value": "{USERNAME}" + }, + // Click the next button to proceed to the next step of the login process. + { + "step": 3, + "command": "click", + "target": "id=next_button", + "value": "" + }, + // Pause the script for 5 seconds to allow the next page to load. + { + "step": 4, + "command": "sleep", + "target": "5", + "value": "" + }, + // Type password in the input field name=password. + // When the script is executed, the {SECRET} variable will be replaced with the actual password. + { + "step": 5, + "command": "type", + "target": "name=password", + "value": "{SECRET}" + }, + // Click the submit button to complete the login process. + { + "step": 6, + "command": "click", + "target": "id=submit_button", + "value": "" + } +] +``` diff --git a/docs/manual/admin/console/authorization_manage/assets_authorization.en.md b/docs/manual/admin/console/authorization_manage/assets_authorization.en.md new file mode 100644 index 000000000..fd3ccb3c0 --- /dev/null +++ b/docs/manual/admin/console/authorization_manage/assets_authorization.en.md @@ -0,0 +1,72 @@ +# Asset Authorization + +## 1 Overview +!!! tip "" + - Click the **Console** button on the navigation bar to open the **Console** page. + - Click **Asset Management > Asset Authorization** to open the **Asset Authorization** page. + - Asset authorization rules restrict user access to assets, ensuring users can only access authorized assets through specific rules. + +## 2 Create asset authorization + +!!! tip "" + - Click the `Create` button on the asset authorization page and fill in the authorization rule information and submit. + +![V4_authorization_1](../../../../img/V4_authorization_1.png) + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | +|-----------|-------------| +| Name | The name of the authorization rule | +| Users | JumpServer login users, i.e., users authorized to connect to assets | +| User Groups | JumpServer login user groups, i.e., user groups authorized to connect to assets | +| Assets | Authorized assets, i.e., assets that users can connect to | +| Nodes | Authorized nodes, i.e., asset groups that users can connect to | +| Account | Accounts for logging in to authorized assets, supports:
    • **All accounts**: All accounts on the asset
    • **Specified accounts**: Manually enter account names
    • **Virtual accounts**:
      ◦ **Manual accounts**: Manually enter username/password during connection
      ◦ **Same-name accounts**: Use accounts with the same name as JumpServer login user
      ◦ **Anonymous accounts**: Do not prefill authentication information, only launch the application itself (suitable for Web/custom assets) | +| Protocols | Protocols available to authorized users, supports:
    • **All**: Any protocol can be used
    • **Specified protocols**: Only specified protocols can be used | +| Actions | Operations that users can perform on assets, including connection, upload, download, clipboard (RDP/VNC), SSH session sharing, etc. | +| Start Date | The effective date of the authorization rule, defaults to creation time | +| Expiration Date | The expiration date of the authorization rule | + + +## 3 Authorization logic explanation +!!! info "" + - **Combined authorization**: When both users and user groups are selected, all users are effective; when both assets and nodes are selected, all assets are effective, using an "AND" relationship + - **Empty options are invalid**: When any required field (users/user groups, assets/nodes, accounts, etc.) is empty, the authorization rule does not take effect + - **Wildcards not supported**: Authorization rules do not support `*` wildcard matching + + +## 4 Authorization examples + +### 4.1 Single user single asset authorization +!!! tip "" + - Authorize only a specific user to access a specific asset: + - Users module: Select the user to authorize, leave user group empty + - Assets module: Select the asset to log in to, leave node empty, select account to authorize (e.g., all accounts) + - Example authorization rule: + ![V4_authorization_2](../../../../img/V4_authorization_2.png) + +### 4.2 User group single asset authorization +!!! tip "" + - Allow a user group to log in to one asset: + - Users module: Select the user group to authorize, leave user empty + - Assets module: Select the asset to log in to, leave node empty, select account to authorize (e.g., all accounts) + - Example authorization rule: + ![V4_authorization_5](../../../../img/V4_authorization_5.png) + +### 4.3 Single user node authorization +!!! tip "" + - Allow a specific user to log in to a group of assets: + - Users module: Select the user to authorize, leave user group empty + - Assets module: Select the asset group to log in to, leave asset empty, select account to authorize (e.g., all accounts) + - Example authorization rule: + ![V4_authorization_8](../../../../img/V4_authorization_8.png) + +### 4.4 User group node authorization +!!! tip "" + - Allow a user group to log in to a group of assets: + - Users module: Select the user group to authorize, leave user empty + - Assets module: Select the asset group to log in to, leave asset empty, select account to authorize (e.g., all accounts) + - Example authorization rule: + ![V4_authorization_10](../../../../img/V4_authorization_10.png) diff --git a/docs/manual/admin/console/authorization_manage/session_sharing.en.md b/docs/manual/admin/console/authorization_manage/session_sharing.en.md new file mode 100644 index 000000000..27d113550 --- /dev/null +++ b/docs/manual/admin/console/authorization_manage/session_sharing.en.md @@ -0,0 +1,21 @@ +# Session Sharing + +## Feature introduction +!!! tip "" + - After a user successfully connects to an asset through Web Terminal, they can create a sharing link on the page and send the sharing link and verification code to other users. + - Other users can access the link, enter the verification code, and after logging in successfully, perform multi-user collaborative operations. + - On the Web Terminal session page, you can see all online users in the session. + - For activity records of shared session participants, administrators can view them in the "Activity" page under the "Session Management" menu and perform related audit operations. + +## Usage method +!!! tip "" + - In the left navigation bar of the console, click **Authorization Management**. +![image](../../../../img/session_sharing01.png) + +!!! tip "" + - In the sharing link, you can modify the **validity period**, **operation permissions**, and **shared users**. After completing the settings, click **Create sharing link**. +![image](../../../../img/session_sharing02.png) + +!!! tip "" + - Copy the link and verification code to the corresponding user. The user accesses the link, enters the verification code, and after logging in successfully, can perform operations. +![image](../../../../img/session_sharing03.png) diff --git a/docs/manual/admin/console/else/tag_list.en.md b/docs/manual/admin/console/else/tag_list.en.md new file mode 100644 index 000000000..284689f2f --- /dev/null +++ b/docs/manual/admin/console/else/tag_list.en.md @@ -0,0 +1,51 @@ +# Tag Management + +## 1 Feature Overview + +!!! tip "" + - Click the **Console** button on the navigation bar to open the **Console** page. + - Click **Other > Tag List** to open the **Tag List** page. + - JumpServer provides tagging functionality supporting adding tags to assets, users, and accounts for convenient resource querying and management. Users can customize various resource properties as tags to achieve resource classification, summarization, and analysis. Tags also support advanced features such as endpoint rules and application server binding, meeting distributed architecture deployment requirements. + +## 2 Creating Tags + +!!! tip "" + - Click the **Create** button in the top-left of the tag management page to open the tag creation page. +![tag_list_01](../../../../img/v4_tag_list_01.png) + +!!! tip "Tag Configuration Instructions" + - Tag information contains two parts: name and value. + - **Name**: Used to describe the functional category of the tag, such as "Purpose", "Department", etc. + - **Value**: Records specific tag information, such as "Organization-R&D Department-Frontend Team". + - Tags can be added to assets during asset creation. Tag names can be repeated, and a single asset can be bound to multiple tags. + - After deleting a tag, assets previously bound to that tag will automatically remove the corresponding tag information. + +## 3 Tag Binding + +!!! tip "" + - Select the tags to be bound when creating assets. +![tag_list_02](../../../../img/v4_tag_list_02.png) + +## 4 Using Tags + +!!! tip "" + - Click on the resource count value in the tag list to add tags in bulk to existing resources. +![tag_list_03](../../../../img/v4_tag_list_03.png) + +!!! tip "" + - On the asset list page, users can quickly locate target assets through tag filtering functionality. +![tag_list_04](../../../../img/v4_tag_list_04.png) + +## 5 Remote Application Server Tag Binding + +!!! info "" + - In distributed, multi-region system deployment environments, administrators can deploy multiple application servers to improve user access efficiency. Through JumpServer's tagging functionality, precise scheduling of specific servers accessing specific assets can be achieved, optimizing resource allocation and access performance. + +!!! tip "" + - Create server binding tags and configure in the following format: + + | Tag Name | Value | Description | + | --- | --- | --- | + | Server | Server name | Specify the server handling this asset access request | + + - Select target assets from the asset list and add corresponding server tags to them. diff --git a/docs/manual/admin/console/users/user-groups.en.md b/docs/manual/admin/console/users/user-groups.en.md new file mode 100644 index 000000000..3c7409053 --- /dev/null +++ b/docs/manual/admin/console/users/user-groups.en.md @@ -0,0 +1,60 @@ +# User Group Management +## 1 Overview +!!! tip "" + - Click the **Console** button on the navigation bar to open the **Console** page. + - Click **User Management > User Groups** to open the **User Group List** page. + - This page is used to manage JumpServer user groups, including creating, deleting, updating, and viewing user groups. + - User groups organize users into groups. When assigning asset permissions, you can authorize entire user groups; a single user can join multiple user groups. +![users_01](../../../../img/v4_user-groups_01.png) +## 2 Create a user group +!!! tip "" + - Click the Create button on the user group page to open the user group creation page. + - Fill in the user group information and click Submit to complete the creation. +![users_02](../../../../img/v4_user-groups_02.png) +!!! tip "" + - Detailed parameter descriptions: + +| Parameter | Description | +|-----------|-------------| +| Name | The user group name | +| Users | Add users to the user group | + +## 3 User group import/export +!!! tip "" + - User groups support import for creation and export of existing user groups, supporting xlsx and csv table formats. + - For the first import, click Import to download a template, fill in the information as prompted, and then import. +![users_03](../../../../img/v4_user-groups_03.png) + +## 4 User group details +!!! tip "" + - Click the user group name on the user group list page to open the user group detail page. + - The user group detail page contains the user group basic information and activity logs. +![users_04](../../../../img/v4_user-groups_04.png) +!!! tip "" + - Detailed parameter descriptions: + +| Parameter | Description | +|-----------|-------------| +| Basic Info | The basic info page displays detailed information about the user group, including ID, name, member count, creator, and more. | +| Members | This option allows you to add or remove members from the user group. | +| Activity Logs | This option records activity logs for the user group, including creation time, creator, and other information. | + +## 5 Update user group +!!! tip "" + - When user group information changes, you can update the user group. Click the Edit button next to the corresponding user group to open the user group info page, make changes, and click Submit. +![users_05](../../../../img/v4_user-groups_05.png) + +## 6 Clone user group +!!! tip "" + - When you need to clone a user group, click the More button next to the user group and select Copy. +![users_06](../../../../img/v4_user-groups_06.png) + +## 7 Delete user group +!!! tip "" + - When you need to delete a user group, click the More button next to the user group and select Delete. +![users_07](../../../../img/v4_user-groups_07.png) + +## 8 Bulk operations on user group list +!!! tip "" + - Select the checkboxes next to user group names to perform bulk deletion operations from the More menu. + ![users_08](../../../../img/v4_user-groups_08.png) diff --git a/docs/manual/admin/console/users/users.en.md b/docs/manual/admin/console/users/users.en.md new file mode 100644 index 000000000..fc6a2be04 --- /dev/null +++ b/docs/manual/admin/console/users/users.en.md @@ -0,0 +1,122 @@ +# User Management +## 1 Overview +!!! tip "" + - Click the **Console** button on the navigation bar to open the **Console** page. + - Click **User Management > User List** to open the **User List** page. + - This page is mainly used to manage JumpServer users, including creating, deleting, updating and viewing users. +![users_01](../../../../img/v4_users_01.png) +## 2 Create a user +!!! tip "" + - Click the Create button on the user list page to open the user creation detail page. + - From the user list page, click the Create button to enter the user creation detail page. +![users_02](../../../../img/v4_users_02.png) + +!!! info "Note: Organization roles and organization management are X-Pack (Enterprise) features." +!!! tip "" + - Detailed parameter descriptions: + +| Parameter | Description | +| --------- | ----------- | +| Name | The display name for the user; can be duplicated | +| Username | The account used to log in to JumpServer; must be unique | +| Email | The email address associated with the account; must be unique | +| User Group | Manage users by groups, mainly used for asset authorizations; when an asset is authorized to a user group, all users in that group get the corresponding permissions | +| Password Policy | When an admin creates a user, they can set the password or generate a password and send it to the user by email. After successfully submitting the user info, JumpServer will send a password setup email to the provided address. | +| MFA | Multi-Factor Authentication. When enabled, users must enter username/password (first factor) and a one-time code from their MFA device (second factor), providing stronger account protection. | +| Source | Specifies the source of the user, e.g., "Database" for manually created users or "LDAP" for imported users | +| System Role | Determines a user's permissions at the system level (e.g., System Admin, Auditor, User/custom roles) | +| Organization Role (X-Pack) | Determines a user's permissions at the organization level (e.g., Org Admin, Auditor, User/custom roles) | +| Active | Indicates whether the user is active and allowed to log in; inactive users cannot log in | +| Expiration Date | The last date the user is allowed to log in; after this date login is prohibited | +| Mobile | Optional; user's phone number used for receiving MFA SMS | +| WeChat | Optional; user's enterprise WeChat for WeChat-based authentication | +| Note | Optional; admin can add notes about the user | + +## 3 Invite users (X-Pack) +!!! info "Note: Invite users and organization management are X-Pack (Enterprise) features." +!!! tip "" + - Click the Invite User button on the user detail page to use the invite feature. + - This feature is used when a JumpServer user exists in the system but not within the current organization; invite them to join the current organization. + - After clicking Invite User, enter the user to be invited and set their organization role in the popup, then click Submit to save. +![users_03](../../../../img/v4_users_03.png) +## 4 Importing and exporting users +!!! tip "" + - Users can be imported for creation or update, and existing users can be exported. Supported formats: xlsx and csv. + - For the first import, click Import to download a template and fill it according to instructions before importing. +![users_04](../../../../img/v4_users_04.png) +## 5 User details +!!! tip "" + - Click a user's name on the user list page to open the user detail page. + - The user details page contains basic info, authorized assets, asset authorization rules, user authorization rules, and activity logs. +![users_09](../../../../img/v4_users_09.png) +!!! tip "" + - Detailed parameter descriptions: +| Parameter | Description | +| --------- | ----------- | +| Basic Info | Shows detailed user information including ID, name, username, email, roles, creator, etc. | +| Authorized Assets | Lists assets authorized to the user within the current organization | +| Asset Authorization Rules | Lists asset authorization rules that include this user | +| User Login Rules | The login policy settings for this user. You can configure rules to restrict when the user can log in (e.g., only during certain time windows). | +| Activity Logs | The user's login/activity records | +| Activate | Quick action button to allow or disallow this user from logging in | +| Reset MFA | Quick action to reset the user's MFA to initial state; the user must re-bind MFA on next login | +| Reset Password | Quick action to send a password reset email to the user | +| Reset SSH Key | Quick action to send a reset SSH Key email to the user | +| Unlock User | Quick action to unlock a user who has been locked due to multiple failed login attempts | +| User Groups | Quick action to add the user to a group via a select box or remove them via the delete button next to joined groups | + +### 5.1 User Login Rules +!!! tip "" + - Click the User Login Rules button on the user detail page to set rules that limit the user's login IPs and login time windows. + - Configure the login rule on this page and click Submit to save and apply. +![users_05](../../../../img/v4_users_05.png) +!!! tip "" + - Detailed parameter descriptions: +| Parameter | Description | +| --------- | ----------- | +| Name | The name of the login rule | +| Priority | The priority of the rule; lower numbers have higher priority | +| IP Group | The IPs restricted by this rule, specified as a comma-separated string. Use * to match all. Examples: 192.168.10.1, 192.168.1.0/24, 10.1.1.1-10.1.1.20, 2001:db8:2de::e13,2001:db8:1a:1110::/64. These IPs refer to the user's source IP when logging in. | +| Time Window | The time period during which the rule applies | +| Action | The action when the rule is executed: **Deny**, **Allow**, or **Login Review**. These mean deny login, allow login, or require approval from specified approvers before login, respectively. | +| Enabled | Whether the login rule is active | + +## 6 Updating user information +!!! tip "" + - To update a user's information, click the edit button next to the user on the user list page to edit and update the user's info. +![users_06](../../../../img/v4_users_06.png) +## 7 Clone user +!!! tip "" + - If a user's information is identical or mostly identical to another, click the More button next to the user and choose Copy to open the user form with prefilled values. Modify the necessary fields and submit. +![users_07](../../../../img/v4_users_07.png) +## 8 Delete / Remove user +!!! tip "" + - To remove a user from the current organization, click More next to the user and select Remove (the user can be re-invited to the organization later). + - To delete a user from the entire JumpServer system, click More next to the user and select Delete (this will remove the user data from the database and is irreversible). +![users_08](../../../../img/v4_users_08.png) + +## 9 Bulk operations on the user list +!!! tip "" + - Select the checkboxes before user names to perform bulk operations such as bulk removal, disable, activate, etc., from the More menu. +![users_10](../../../../img/v4_users_10.png) + +## 10 Quick user actions +### 10.1 Unlock user +!!! tip "" + - When a user is temporarily locked due to multiple failed logins, the administrator can unlock the user. On the user list, click the user and use the quick update card on the right of Basic Info to unlock the user. +![users_11](../../../../img/v4_users_11.png) + +### 10.2 Reset password +!!! tip "" + - If a user forgets their password, an admin can send a reset email. The user can then set a new login password. On the user list, click a user and in the Basic Info right panel click Reset Password > Send Email. The system will send a password reset email. In the email the user clicks "Click here to reset password" to open the reset page, enters and confirms the new password, then clicks Submit. The user will receive a notification email after a successful password reset. +![users_12](../../../../img/v4_users_12.png) + +### 10.3 Reset SSH keys +!!! tip "" + - On the user list, click a user and find the Reset SSH Key section in the Basic Info right panel, then click Send. Confirm in the popup. The system will send a reset SSH key email. In the email the user clicks "Click here to set" to open the SSH key page, where they can add or remove SSH keys. +![users_13](../../../../img/v4_users_13.png) + +### 10.4 Reset MFA +!!! tip "" + - If a user cannot log in because their MFA is lost, an admin can reset the user's MFA. In the Basic Info right panel find Reset MFA and click the Reset button. +![users_14](../../../../img/v4_users_14.png) diff --git a/docs/manual/admin/others/MFA_Facelive.en.md b/docs/manual/admin/others/MFA_Facelive.en.md new file mode 100644 index 000000000..2fec5fe23 --- /dev/null +++ b/docs/manual/admin/others/MFA_Facelive.en.md @@ -0,0 +1,48 @@ +# MFA Face Recognition +!!! info "Note: Face recognition is a flagship edition feature." +> 1. Version: v4.6.0 and above
    +> 2. Flagship edition license with 5000+ assets
    +> 3. HTTPS access enabled + +## 1 Configure Face Recognition +!!! tip "" + **Add new parameters** + ```sh + vim /opt/jumpserver/config/config.txt + #config.txt + USE_XPACK=1 + FACE_RECOGNITION_ENABLED=true + FACELIVE_ENABLED=1 + ``` + **Restart JumpServer** + ```sh + jmsctl restart + ``` + +## 2 Configure MFA Face Recognition +!!! tip "" + - Record facial information on the user detail page and enable MFA. + +![image.png](../../../../img/Facelive1.png) + +!!! tip "" + - Log out and try logging in again, select face verification. +![image.png](../../../../img/Facelive2.png) + +!!! tip "" + - Complete facial verification within 30 seconds. +![image.png](../../../../img/Facelive3.png) + +## 3 Asset connection face recognition and monitoring +!!! tip "" + - Enable **Face Verification** in **Console > Access Control > Asset Connection**. The operation can be **Face Verification** or **Face Online**. +![image.png](../../../../img/Facelive4.png) + +!!! tip "" + - Face verification is required before connecting to an asset. +![image.png](../../../../img/Facelive5.png) + +!!! tip "" + - If facial recognition does not detect the user, the session will be paused. + - During the paused session, no operations on the asset can be performed. +![image.png](../../../../img/Facelive6.png) diff --git a/docs/manual/admin/pam/applications_manage.en.md b/docs/manual/admin/pam/applications_manage.en.md new file mode 100644 index 000000000..10dce34da --- /dev/null +++ b/docs/manual/admin/pam/applications_manage.en.md @@ -0,0 +1,27 @@ +# Application Management + +## 1 Overview +!!! info "Note: Application management is a JumpServer Enterprise edition feature." +!!! tip "" + - Go to the **PAM** page, click **Application Management > Application Management** to open the application management page. + - Application management provides unified invocation and retrieval services of asset accounts and passwords for external systems (accessed via API interface). +![V4_pam_application1](../../../img/V4_pam_application1.png) + +## 2 Create application +!!! tip "" + - Click the **Create** button to create a new application. + - You can set the application name, upload an icon, specify account policy and IP whitelist, set whether to activate, and set notes. +![V4_pam_application2](../../../img/V4_pam_application2.png) + +## 3 Invocation records +!!! tip "" + - Click **Invocation Records** to view the invocation history of the application. +![V4_pam_application3](../../../img/V4_pam_application3.png) + + +## 4 Documentation +!!! tip "" + - Click **Documentation** to view API invocation examples based on cURL, Python, Go, Java, and Node.js. + - This API provides PAM asset account viewing service, supporting RESTful-style invocation and returning data in JSON format. + - For API documentation, please refer to: https://docs.jumpserver.org/en/v4/dev/rest_api/ +![V4_pam_application3](../../../img/V4_pam_application4.png) diff --git a/docs/manual/admin/pam/automation/account_backup.en.md b/docs/manual/admin/pam/automation/account_backup.en.md new file mode 100644 index 000000000..56b1bb76a --- /dev/null +++ b/docs/manual/admin/pam/automation/account_backup.en.md @@ -0,0 +1,32 @@ +# Account Backup +## 1 Overview +!!! tip "" + - Click the **PAM** button on the navigation bar to open the **PAM** page. + - Click **Automation > Account Backup** to open the **Account Backup** page. + - To prevent uncontrollable factors such as server data corruption and asset account loss that may prevent the environment from running normally, JumpServer supports an account backup feature that can backup all asset accounts on JumpServer. Backup strategies can be immediate or scheduled backup. +## 2 Account backup task +!!! tip "" + - Click the **Create** button on the **Account Backup Task** page to create an automation task for account backup. Fill in the account backup task information completely and confirm settings to create. +![automation_01](../../../../img/v4_account_backup_01.png) +!!! tip "" + - Detailed parameter descriptions: +|Parameter|Description| +|--------|-------------------| +|Name|The name of the account backup task| +|Type|The type of accounts to backup; backup tasks can be created by account type| +|Backup Type|Account backup method; you can choose to send by email or store to a specified server via SFTP protocol| +|Split secret key into two parts|Whether to split the account secret key into two parts to enhance security; if two recipients or two servers are selected, the secret key file will be split into two parts and sent separately| +|Recipients/Receiving servers|Backup files can be sent to users by email or uploaded to a server via SFTP protocol| +|Periodic execution|Optional; select whether the automation task executes periodically and set the execution time| +|Note|Optional; task notes| + +!!! tip "" + - Select the **Execute** function to execute the account backup function. After execution, you can view the task execution status. +![automation_02](../../../../img/v4_account_backup_02.png) +!!! tip "" + - Click the **More** button next to the account backup task to edit, delete, and copy. +![automation_03](../../../../img/v4_account_backup_03.png) +## 3 Execution history +!!! tip "" + - This page mainly displays the execution history, execution logs, and detailed information about account backups. +![automation_04](../../../../img/v4_account_backup_04.png) diff --git a/docs/manual/admin/pam/automation/account_discovery.en.md b/docs/manual/admin/pam/automation/account_discovery.en.md new file mode 100644 index 000000000..53fcc419e --- /dev/null +++ b/docs/manual/admin/pam/automation/account_discovery.en.md @@ -0,0 +1,30 @@ +# Account Discovery +## 1 Overview +!!! tip "" + - Click the **PAM** button on the navigation bar to open the **PAM** page. + - Click **Automation > Account Discovery** to open the **Account Discovery** page. + - The account discovery feature can collect account information from assets managed by JumpServer. By executing tasks, you can collect asset account information. JumpServer supports binding discovered account information to managed assets, reducing manual operations. +## 2 Discover accounts +!!! tip "" + - After selecting accounts, click **Sync Selected** in the **More** menu to bind collected users to corresponding assets. +![automation_01](../../../../img/v4_account_discovery_01.png) +!!! tip "" + - Click **Delete Synced Selection** in the operations to delete accounts from the server. +![automation_02](../../../../img/v4_account_discovery_02.png) +!!! tip "" + - Click **Delete Selected** in the operations to delete accounts from account discovery. +![automation_03](../../../../img/v4_account_discovery_03.png) +!!! tip "" + - After account binding, the account source will be discovered. +![automation_04](../../../../img/v4_account_discovery_04.png) +## 3 Account discovery task +!!! tip "" + - Click the **Create** button on the **Account Discovery Task** page to create a user discovery task. +![automation_05](../../../../img/v4_account_discovery_05.png) +!!! tip "" + - After successful creation, select the **Execute** button to execute the user collection task. +![automation_06](../../../../img/v4_account_discovery_06.png) +## 4 Execution history +!!! tip "" + - The execution list page mainly displays detailed information and logs of executed user discovery tasks. Click the **Logs** button or **Report** button next to the corresponding executed log to view detailed task execution information. +![automation_07](../../../../img/v4_account_discovery_07.png) diff --git a/docs/manual/admin/pam/automation/account_push.en.md b/docs/manual/admin/pam/automation/account_push.en.md new file mode 100644 index 000000000..104647336 --- /dev/null +++ b/docs/manual/admin/pam/automation/account_push.en.md @@ -0,0 +1,39 @@ +# Account Push +## 1 Overview +!!! tip "" + - Click the **PAM** button on the navigation bar to open the **PAM** page. + - Click **Automation > Account Push** to open the **Account Push** page. + - JumpServer supports automatic user configuration for managed assets. It includes pushing accounts, push task execution history, and execution records. +## 2 Account push task +!!! tip "" + - Click the **Create** button on the **Account Push Task** page to create a user push task. +![automation_01](../../../../img/v4_account_push_01.png) +!!! tip "" + - Detailed parameter descriptions: +|Parameter|Description| +|----------------|-------------------| +|Name|The name of the account push task| +|Assets|Assets that need to have accounts pushed to them| +|Node|Nodes that need to have accounts pushed to them| +|Username|The account name to be pushed to the asset| +|Password Policy - Cipher generation policy|Select the password policy for the user being pushed.
    Specified: The administrator manually enters the password.
    Random: JumpServer generates the password automatically| +|Password Policy - Cipher type|The type of cipher text for the user being pushed| +|Password|If cipher generation policy is specified, the administrator enters the password. If cipher generation policy is random, the administrator sets password generation rules, such as password length, password strength rules, etc.| +|Push parameters|Optional; Windows assets support configuring user groups for pushed accounts (such as Administrators group);
    Unix-like assets support configuring Sudo permissions, shell, home directory, user groups, and user ID for pushed accounts.
    **Currently only effective for assets with platform type of host**| +|Periodic execution|Optional; select whether the automation task executes periodically and set the execution time| +|Check connection after change|When enabled, the pushed account will test account connectivity| +|Active|When enabled, the pushed account will test account connectivity| +|Note|Optional; push task notes| + +## 3 Execute account push +!!! tip "" + - Select the **Execute** button to execute the account push function and view the results. +![automation_02](../../../../img/v4_account_push_02.png) +## 4 Execution history +!!! tip "" + - This page mainly shows the execution logs of account push scheduled tasks. You can click **Logs** on the right side of the execution history to view. +![automation_03](../../../../img/v4_account_push_03.png) +## 5 Execution records +!!! tip "" + - This page is mainly used to view detailed change records of account push scheduled tasks. +![automation_04](../../../../img/v4_account_push_04.png) diff --git a/docs/manual/admin/pam/security/change_secrets.en.md b/docs/manual/admin/pam/security/change_secrets.en.md new file mode 100644 index 000000000..1532ba8fe --- /dev/null +++ b/docs/manual/admin/pam/security/change_secrets.en.md @@ -0,0 +1,69 @@ +# Account Password Change +## 1 Overview +!!! info "Note: Account password change is a JumpServer Enterprise edition feature." +!!! tip "" + - Click the **PAM** button on the navigation bar to open the **PAM** page. + - Click **Security Settings > Account Password Change** to open the **Account Password Change** page. + - Account password change is designed to meet user security requirements by regularly or manually executing tasks to modify user passwords on assets. + - The account password change task changes user passwords on assets using the privileged account of the asset **This operation requires a privileged account in the asset's account list**. + - Account password change currently does not support changing Windows domain account passwords. + +!!! warning "" + - Since **modifying privileged user passwords** is a high-risk operation, JumpServer does not allow modifying privileged user passwords by default. The function to modify asset privileged account passwords is disabled by default and requires administrators to add the option `CHANGE_AUTH_PLAN_SECURE_MODE_ENABLED=false` in the configuration file and restart the bastion machine service to take effect. + +## 2 Overview +!!! tip "" + - JumpServer supports an overview of account password change tasks, where you can view a summary of recent account password change tasks, task execution results, and statistics on successful and failed password changes. The account password change overview page is as follows: +![V4_change_secrets_1](../../../../img/V4_change_secrets_1.png) + + +!!! tip "" + You can view specific failed accounts and reasons for failure in **Failed Password Change Accounts**. If you want to view old and new passwords in password change tasks, click **View** in the operations. This step requires a user with query password permissions to perform MFA verification in JumpServer. +![V4_change_secrets_7](../../../../img/V4_change_secrets_7.png) + + +## 3 Account password change task +!!! tip "" + - Click the **Create** button on the **Account Password Change Task** page to create an automation task for changing account passwords. +![V4_change_secrets_2](../../../../img/V4_change_secrets_2.png) + + +!!! tip "" + - Detailed parameter descriptions: + +| Parameter | Description | +|-----------|-------------| +| Name | The name of the account password change automation task | +| Username | The user whose password will be changed | +| Assets | Assets whose passwords need to be changed | +| Node | Asset node groups whose passwords need to be changed | +| Password Policy - Cipher generation policy | Select the password policy for the user whose password will be changed | +| | • Specified: Administrator manually enters the password | +| | • Random: JumpServer generates the password automatically | +| Password Policy - Cipher type | The type of cipher text for the user whose password will be changed | +| Password | If cipher generation policy is specified, administrator enters the password | +| | If cipher generation policy is random, administrator sets password generation rules, such as password length, password strength rules, etc. | +| Parameters | Parameters are currently only effective for Unix, AIX, Linux type assets | +| Periodic execution | Select whether the automation task executes periodically and set the execution time | +| Recipients | Select users to receive password change notification emails | + +!!! tip "" + - Click the **Execute** button to immediately run the automation task. Click the **More** button to edit, delete, or copy. +![V4_change_secrets_3](../../../../img/V4_change_secrets_3.png) + + +!!! tip "" + - Check the execution logs. +![V4_change_secrets_4](../../../../img/V4_change_secrets_4.png) + + +## 4 Execution history +!!! tip "" + - This page mainly displays detailed information about scheduled account password change tasks, such as execution logs and reports. View the execution logs. +![V4_change_secrets_5](../../../../img/V4_change_secrets_5.png) + + +## 5 Execution records +!!! tip "" + - This page mainly displays records of each account whose password has been changed. You can view new and old passwords and retry changing account passwords. Viewing new and old passwords requires users to perform MFA verification. +![V4_change_secrets_6](../../../../img/V4_change_secrets_6.png) diff --git a/docs/manual/admin/pam/security/risk_detection.en.md b/docs/manual/admin/pam/security/risk_detection.en.md new file mode 100644 index 000000000..c9a60f5fb --- /dev/null +++ b/docs/manual/admin/pam/security/risk_detection.en.md @@ -0,0 +1,64 @@ +# Risk Detection + +## 1 Overview +!!! info "Note: Risk detection is a JumpServer Enterprise edition feature." +!!! tip "" + - Click the **PAM** button on the navigation bar to open the **PAM** page. + - Click **Security Settings > Risk Detection** to open the **Risk Detection** page. + - JumpServer supports account risk detection features that can detect risks such as accounts not logged in for a long time, expired passwords, weak passwords, duplicate passwords, etc., and can export the risk list for review, handling, or ignoring. +![V4_risk_detection_1](../../../../img/V4_risk_detection_1.png) + + +## 2 Detection results +!!! tip "" + - The detection results page displays all account risk types and handling suggestions. You can export the risk list for review, handling, or ignoring. + - If risks such as duplicate passwords or long periods without password changes are detected, you can click the dropdown arrow to the right of the account to update the password or add the account as prompted. You can also directly review the risk content. + - Weak password detection rules include: password length less than 8 characters, containing only a single character type, digits only, or common weak passwords (such as 123456, password, abc123, etc.) + - For different risk types, you can choose operations such as "sync delete", "add account", "add after password change", etc. After handling, the risk status changes to confirmed. If ignored, the status changes to ignored. +![V4_risk_detection_1](../../../../img/V4_risk_detection_1.png) +![V4_risk_detection_3](../../../../img/V4_risk_detection_3.png) +![V4_risk_detection_2](../../../../img/V4_risk_detection_2.png) +![V4_risk_detection_4](../../../../img/V4_risk_detection_4.png) + + + +## 3 Detection task +!!! tip "" + - Click the **Create** button on the detection task page to create an account risk detection task by filling in relevant information. +![V4_risk_detection_5](../../../../img/V4_risk_detection_5.png) + +!!! tip "" + - Detailed parameter descriptions: +| Parameter | Description | +|-----------|------| +| Name | The name of the risk detection task | +| Assets | Assets with accounts that need to be detected | +| Node | Asset node groups with accounts that need to be detected | +| Engine | Check account password strength, whether account passwords are duplicated, whether they are common passwords | +| Recipients | Currently only supports email delivery | +| Periodic execution | Periodic execution settings | +| Active | Whether the task is effective | +| Note | Optional; risk detection task notes | + + +!!! tip "" + - Click the **Execute** button to immediately run the detection task. Click **More** to edit, delete, or copy the task. +![V4_risk_detection_6](../../../../img/V4_risk_detection_6.png) + +!!! tip "" + - You can view the execution logs of the detection task. +![V4_risk_detection_8](../../../../img/V4_risk_detection_8.png) + + + +## 4 Execution history +!!! tip "" + - Displays the history of account risk detection tasks. You can view logs or reports. +![V4_risk_detection_7](../../../../img/V4_risk_detection_7.png) + + + +## 5 Detection engine +!!! tip "" + - Displays currently supported detection engines and their descriptions. +![V4_risk_detection_9](../../../../img/V4_risk_detection_9.png) diff --git a/docs/manual/admin/system_settings/appearance.en.md b/docs/manual/admin/system_settings/appearance.en.md new file mode 100644 index 000000000..bb130bd31 --- /dev/null +++ b/docs/manual/admin/system_settings/appearance.en.md @@ -0,0 +1,40 @@ +# Appearance Settings +!!! tip "" + - Click the settings icon in the top right corner of the page to enter the **System Settings** page, then click **Appearance Settings** to access the appearance configuration page. + - Appearance settings mainly include: login page title settings, JumpServer overall theme settings, JumpServer logo settings, login page image settings, and ICP filing number settings. +![V4_appearance_01.png](../../../img/V4_appearance_01.png) + +## 1 Basic Settings +!!! tip "" + - Basic settings include login page title and theme. The login page title can be customized. After customization, it displays as follows: +![V4_appearance_02.png](../../../img/V4_appearance_02.png) +!!! tip "" + - View the title settings on the page: +![V4_appearance_03.png](../../../img/V4_appearance_03.png) +!!! tip "" + - JumpServer supports multiple theme switches. Currently supported themes include: China Red, Deep Black, Tech Blue, Classic Green, and Noble Purple. +![V4_appearance_04.png](../../../img/V4_appearance_04.png) + +## 2 Logo +!!! tip "" + - The `Top Wide Logo` option, after adjustment, will be displayed in the top left of the admin page, as shown below: +![V4_appearance_05.png](../../../img/V4_appearance_05.png) +!!! tip "" + - After adjusting the `Small Square Logo` option, it will be displayed as a small icon on the web terminal for enterprise edition users, as shown below: +![V4_appearance_06.png](../../../img/V4_appearance_06.png) +!!! tip "" + - After adjusting the `Website Icon` option, it will be displayed as a small icon on the left side of the browser tab, as shown below: +![V4_appearance_07.png](../../../img/V4_appearance_07.png) + +## 3 Images +!!! tip "" + - The `Login Page Image`, after adjustment, is displayed on the right side of the login input box, as follows: +![V4_appearance_08.png](../../../img/V4_appearance_08.png) + +## 4 Footer +!!! tip "" + - Update the footer content on the appearance page: +![V4_appearance_10.png](../../../img/V4_appearance_10.png) +!!! tip "" + - After adjusting the record information, it will be displayed at the bottom of the login page, as shown below: +![V4_appearance_09.png](../../../img/V4_appearance_09.png) diff --git a/docs/manual/admin/system_settings/authentication_settings/Feishu.en.md b/docs/manual/admin/system_settings/authentication_settings/Feishu.en.md new file mode 100644 index 000000000..6cb9811a5 --- /dev/null +++ b/docs/manual/admin/system_settings/authentication_settings/Feishu.en.md @@ -0,0 +1,39 @@ +# Feishu Authentication + +## 1 About Feishu + +!!! info "Note: Feishu authentication is an enterprise version feature of JumpServer." +!!! tip "" + - Click the settings icon in the top right corner of the page to enter the **System Settings** page, then click **Authentication Settings > Feishu** to access the Feishu configuration page. + - **Feishu Authentication** is an identity authentication method based on the Feishu platform. JumpServer supports QR code login and enterprise identity binding. + +## 2 Basic Configuration + +!!! tip "" + Detailed parameter description: + +| Parameter | Description | Example | +|-----------|-------------|---------| +| Feishu | Check to enable Feishu identity verification | Enable/Disable | +| App ID | Feishu App ID, which is the unique identifier of the application | | +| App secret | Feishu application secret key, similar to a password for API access, used to obtain access tokens for calling Feishu APIs | | +| Attribute Mapping | User attribute mapping. The key represents the JumpServer user attribute name, and the value corresponds to the Feishu user attribute name | See examples below | +| Organization | After authentication and creation, users will be added to the selected organization | Default value: `DEFAULT` | + +Feishu User Attribute Example +!!! tip "Attribute Mapping Example" + +```json +{ + "name": "nickname", + "username": "user_id", + "email": "email" +} +``` + +## 3 JumpServer Feishu URL Description + +| URL Type | Address | Description | +|----------|---------|-------------| +| QR Code Login URL | `https://jumpserver.example.com/core/auth/feishu/qr/login/` | Feishu QR code login entry | +| QR Code Login Callback URL | `https://jumpserver.example.com/core/auth/feishu/qr/login/callback/` | QR code login success callback address | diff --git a/docs/manual/admin/system_settings/authentication_settings/LDAP.en.md b/docs/manual/admin/system_settings/authentication_settings/LDAP.en.md new file mode 100644 index 000000000..a34ca15ee --- /dev/null +++ b/docs/manual/admin/system_settings/authentication_settings/LDAP.en.md @@ -0,0 +1,103 @@ +# LDAP Authentication + +## About LDAP + +!!! tip "" + - Click the gear icon in the top-right corner to enter the **System Settings** page, then click **Authentication Settings > LDAP** to open the LDAP configuration page. + - **Lightweight Directory Access Protocol (LDAP)** is an open protocol used to access and manage distributed directory information. It is primarily used for centralized identity authentication and directory services, such as storing user accounts, permissions, and organizational structure information. LDAP is widely used in enterprise identity management, single sign-on (SSO), and access control systems. + - **Distinguished Name (DN)** is the unique identifier for each entry in the LDAP directory, similar to the full path in a file system, for example `cn=admin,ou=Users,dc=example,dc=com`. + - **Organizational Unit (OU)** is used to organize and manage objects in the LDAP directory, similar to directory structure in a file system. For example, an organization may contain multiple OUs such as `ou=HR` and `ou=IT` to distinguish users and resources from different departments. + +## Basic Configuration + +!!! tip "" + - Click the settings button in the top-right corner + - Navigate to **System Settings > Authentication Settings > LDAP** + +!!! info "" + - To configure LDAP TLS certificates, upload `ldap_ca.pem`, `ldap_cert.pem`, and `ldap_cert.key` files to the JumpServer `/data/jumpserver/core/data/certs` directory, then restart JumpServer using the command `jmsctl restart`. + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | Example | +| --- | --- | --- | +| LDAP | Enable LDAP authentication | Enable/Disable | +| Server | LDAP server URI | `ldap://example.com:389` or `ldaps://example.com:636` | +| Bind DN | User DN with query permissions for querying and filtering users | `cn=admin,dc=example,dc=com` or `user@domain.com` format | +| Password | Password for bind DN user | | +| User OU | Search starting OU, specifying where to start searching for users; multiple values separated by `\|` | `ou=users,dc=example,dc=com\|ou=tech,dc=example,dc=com` | +| User Filter | Filter expression for searching LDAP users | Default expression: `(cn=%(user)s)` | +| Mapped Attributes | User attribute mapping; key represents JumpServer user attribute name, value corresponds to LDAP user attribute name | See example below | +| Strict Mode | When strict mode is enabled, full or automatic synchronization will disable users not found in LDAP | | +| Connection Timeout | LDAP connection timeout (unit: seconds) | Default: 30 seconds | +| Search Pagination (items) | Page size for searching users | Default: 1000 | +| User DN Cache Timeout (seconds) | Cache duration for user DN (unit: seconds) to improve login verification speed. If user DN changes, resubmit the form to clear cache, or authentication will fail | Default: 3600 seconds | + +LDAP User Attribute Example + +!!! tip "" + - The **Mapped Attributes** field is used to set user attribute mapping. The key represents JumpServer user attribute name, and the value corresponds to LDAP user attribute name. + +```json +{ + "name": "sAMAccountName", + "username": "cn", + "email": "mail", + "is_active": "useraccountcontrol", + "phone": "telephoneNumber", + "groups": "memberof" +} +``` + +## Test LDAP Connection + +!!! tip "" + - Click the settings button in the top-right corner + - Navigate to **System Settings > Authentication Settings > LDAP** + - Scroll to the bottom of the page + - Click **Test Connection** + +## Test LDAP Login + +!!! tip "" + - Click the settings button in the top-right corner + - Navigate to **System Settings > Authentication Settings > LDAP** + - Ensure LDAP configuration has been successfully completed and tested + - Scroll to the bottom of the page + - Click **Test Login** + - Enter LDAP user's username and password in the popup window + +## Import LDAP Users + +!!! tip "" + - Click the settings button in the top-right corner + - Navigate to **System Settings > Authentication Settings > LDAP** + - Ensure LDAP configuration has been successfully completed and tested + - Scroll to the bottom of the page + - Click **User Import** + - In the popup window, you can import LDAP users in the following ways + - Click **Sync Users** to synchronize LDAP users to the list + - In the **Import Organization** field, select one or more organizations to import to + - Select users to import and click **Import** to proceed; or click **Import All** to import all users + +![LDAP Figure 1](../../../../img/V4_LDAP1.png) + +## Set LDAP User Synchronization + +!!! tip "" + - Click the settings button in the top-right corner + - Navigate to **System Settings > Authentication Settings > LDAP** + - Ensure LDAP configuration has been successfully completed and tested + - Scroll to the bottom of the page + - Click **Sync Settings** + - In the popup window, enter the following configuration information + - In the **Organization** field, select one or more organizations to sync + - In the **Periodic Execution** field, check to enable periodic execution + - In the **Scheduled Task** field, enter a crontab expression. If empty, **Interval** setting will be used + - In the **Interval** field, enter sync interval time (unit: hours) + - Note: If **Scheduled Task** has a value, **Scheduled Task** takes priority + - In the **Recipients** field, select one or more users to receive sync results + - Click **Confirm** + +![LDAP Figure 2](../../../../img/V4_LDAP2.png) diff --git a/docs/manual/admin/system_settings/authentication_settings/LDAPHA.en.md b/docs/manual/admin/system_settings/authentication_settings/LDAPHA.en.md new file mode 100644 index 000000000..d0047b3ba --- /dev/null +++ b/docs/manual/admin/system_settings/authentication_settings/LDAPHA.en.md @@ -0,0 +1,64 @@ +# LDAP HA Authentication + +## About LDAP HA + +!!! info "Note: LDAP HA authentication is an enterprise feature of JumpServer." + +!!! tip "" + - Click the gear icon in the top-right corner to enter the **System Settings** page, then click **Authentication Settings > LDAP HA** to open the LDAP HA configuration page. + - In JumpServer, LDAP HA integration typically ensures that when the primary LDAP server fails, the system automatically switches to a backup LDAP HA server, ensuring continuity of authentication services. Thus, even if the LDAP server encounters problems, JumpServer can continue processing user authentication requests without causing downtime or service interruption. + +## Basic Configuration + +!!! tip "" + - Click the settings button in the top-right corner + - Navigate to **System Settings > Authentication Settings > LDAP HA** + - In the **Server Address** field, enter the LDAP HA server URI, such as "ldap://example.com:389" and "ldaps://example.com:636". + +!!! info "" + - To configure LDAP TLS certificates, upload `ldap_ca.pem`, `ldap_cert.pem`, and `ldap_cert.key` files to the JumpServer `/data/jumpserver/core/data/certs` directory, then restart JumpServer using the command `jmsctl restart`. + +!!! tip "" + - In the **Bind DN** field, enter a user DN with at least query permissions; this permission will be used to query and filter users, for example "cn=admin,dc=example,dc=com". + - In the **Mapped Attributes** field, enter user attribute mapping. The key represents JumpServer user attribute name (available options: name, username, email, is_active, groups, phone, comment), and the value corresponds to LDAP HA user attribute name. + +```json +{ + "name": "sAMAccountName", + "username": "cn", + "email": "mail", + "is_active": "useraccountcontrol", + "phone": "telephoneNumber", + "groups": "memberof" +} +``` + +## Test LDAP HA Connection + +!!! tip "" + - Click the settings button in the top-right corner + - Navigate to **System Settings > Authentication Settings > LDAP HA** + - Scroll to the bottom of the page + - Click **Test Connection** + +## Test LDAP Login + +!!! tip "" + - Click the settings button in the top-right corner + - Navigate to **System Settings > Authentication Settings > LDAP HA** + - Ensure LDAP HA configuration has been successfully completed and tested + - Scroll to the bottom of the page + - Click **Test Login** + - Enter LDAP user's username and password in the popup window + - Click **Confirm** + +## Import LDAP Users + +!!! tip "" + - Click the settings button in the top-right corner + - Navigate to **System Settings > Authentication Settings > LDAP HA** + - Ensure LDAP HA configuration has been successfully completed and tested + - Scroll to the bottom of the page + - Click **User Import** + - In the popup window, click **Sync Users** to synchronize LDAP HA users to the list + - Select users to import and click **Import** to proceed; or click **Import All** to import all users diff --git a/docs/manual/admin/system_settings/authentication_settings/Lark.en.md b/docs/manual/admin/system_settings/authentication_settings/Lark.en.md new file mode 100644 index 000000000..fe284e205 --- /dev/null +++ b/docs/manual/admin/system_settings/authentication_settings/Lark.en.md @@ -0,0 +1,43 @@ +# Lark Authentication + +## About Lark +!!! info "Note: Lark authentication is an enterprise version feature of JumpServer." +!!! tip "" + - Click the settings icon in the top right corner of the page to enter the **System Settings** page, then click **Authentication Settings > Lark** to access the Lark configuration page. + - **Lark** Authentication is an identity authentication mechanism provided by Lark (international version of Feishu) that enables enterprises and third-party applications to authenticate and authorize users through Lark. + +## Basic Configuration + +!!! tip "" + - Click the settings icon in the top right corner of the page + - Navigate to **System Settings > Authentication Settings > Lark** + +!!! tip "" + Detailed parameter description: + +| Parameter | Description | Example | +|-----------|-------------|---------| +| Lark | Check to enable Lark identity verification | Enable/Disable | +| App ID | Lark App ID, which is the unique identifier of the application | | +| App secret | Lark application secret key, used to obtain access tokens for calling Lark APIs | | +| Attribute Mapping | User attribute mapping. The key represents the JumpServer user attribute name, and the value corresponds to the Lark user attribute name | See examples below | +| Organization | After authentication and creation, users will be added to the selected organization | Default value: `DEFAULT` | + +Lark User Attribute Example +!!! tip "" + - The **Attribute Mapping** field is used to set user attribute mapping. The key represents the JumpServer user attribute name, and the value corresponds to the Lark user attribute name. + +```json +{ + "name": "nickname", + "username": "user_id", + "email": "email" +} +``` + +## JumpServer Lark URL Description + +| URL Type | Address | Description | +|----------|---------|-------------| +| QR Code Login URL | `https://jumpserver.example.com/core/auth/lark/qr/login/` | Lark QR code login entry | +| QR Code Login Callback URL | `https://jumpserver.example.com/core/auth/lark/qr/login/callback/` | QR code login success callback address | diff --git a/docs/manual/admin/system_settings/authentication_settings/OAuth2.en.md b/docs/manual/admin/system_settings/authentication_settings/OAuth2.en.md new file mode 100644 index 000000000..c6bb3914c --- /dev/null +++ b/docs/manual/admin/system_settings/authentication_settings/OAuth2.en.md @@ -0,0 +1,48 @@ +# OAuth2 Authentication + +## 1 About OAuth2 + +!!! info "Note: OAuth2 authentication is an enterprise feature of JumpServer." + +!!! tip "" + - Click the gear icon in the top-right corner to enter the **System Settings** page, then click **Authentication Settings > OAuth2** to open the OAuth2 configuration page. + - **OAuth2** is an open third-party authorization protocol. JumpServer supports standard OAuth2 platform authentication. + +## 2 Configuration Parameters + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | Example | +| --- | --- | --- | +| OAuth2 | Enable OAuth2 identity authentication | Enable/Disable | +| Service Provider | OAuth2 service provider name | `GitHub`, `Google`, `Facebook`, etc. | +| Icon | Service provider icon displayed on login page; recommended size: 64x64 pixels | | +| Client ID | Client ID provided by OAuth2 service provider | | +| Client Secret | Client Secret provided by OAuth2 service provider | | +| Client Authentication Method | Authentication method for obtaining token; see explanation below | | +| Scope | Scope range for authorization request, space-separated | `user user:email user:login` | +| Authorization Endpoint Address | OAuth2 Authorization Endpoint | `https://github.com/login/oauth/authorize` | +| Token Endpoint Address | OAuth2 Token Endpoint | `https://github.com/login/oauth/access_token` | +| User Info Endpoint Address | OAuth2 UserInfo Endpoint | `https://api.github.com/user` | +| Logout Endpoint Address | OAuth2 Logout Endpoint, called when user logout | `https://github.com/logout` | +| Mapped Attributes | User attribute mapping; correspondence between JumpServer and OAuth2 fields | See JSON example below | +| Organization | After authentication and creation, user will be added to the selected organization | Default: DEFAULT | +| Always Update User Info | When enabled, synchronize user info on every authentication (only name, username, email, phone, comment; groups only on first sync) | Enable/Disable | +| Sync Logout | When enabled, logout is synchronized with OAuth2 service logout | Enable/Disable | + +!!! tip "" + - Client authentication method explanation: + +| Request Method | Description | +| --- | --- | +| Client Secret Basic | Use POST method to obtain token; Client ID and Client Secret included in request header | +| Client Secret Post | Use POST method to obtain token; Client ID and Client Secret included in request body as raw data | + +JumpServer OAuth2 URL Description + +| URL Type | Address | Description | +| --- | --- | --- | +| OAuth2 Login URL | `https://jumpserver.example.com/core/auth/oauth2/login/` | OAuth2 login entry point | +| OAuth2 Login Callback URL | `https://jumpserver.example.com/core/auth/oauth2/login/callback/` | OAuth2 login success callback address | +| Logout URL | `https://jumpserver.example.com/core/auth/oauth2/logout/` | OAuth2 logout address | diff --git a/docs/manual/admin/system_settings/authentication_settings/OIDC.en.md b/docs/manual/admin/system_settings/authentication_settings/OIDC.en.md new file mode 100644 index 000000000..2cfdeaf55 --- /dev/null +++ b/docs/manual/admin/system_settings/authentication_settings/OIDC.en.md @@ -0,0 +1,44 @@ +# OIDC Authentication + +## 1 About OIDC + +!!! info "Note: OIDC authentication is an enterprise feature of JumpServer." + +!!! tip "" + - Click the gear icon in the top-right corner to enter the **System Settings** page, then click **Authentication Settings > OIDC** to open the OIDC configuration page. + - **OpenID Connect (OIDC)** is an identity authentication protocol based on OAuth 2.0. JumpServer authentication supports standard OIDC authentication. + +## 2 Basic Configuration + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | Example | +| --- | --- | --- | +| OIDC | Check to enable OIDC authentication | Enable/Disable | +| JumpServer Address | Complete domain name of JumpServer, used to construct callback URL | `https://jumpserver.example.com/` | +| Client ID | Client ID provided by OIDC server | | +| Client Secret | Client Secret provided by OIDC server | | +| Client Authentication Method | Authentication method: Client Secret Basic (use POST method to obtain token with Client ID and Client Secret in request header); Client Secret Post (use POST method to obtain token with Client ID and Client Secret in request body) | | +| Use Keycloak | Select to use Keycloak configuration, or uncheck to use native OIDC configuration | | + +### 2.1 Using Keycloak + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | Example | +| --- | --- | --- | +| Server Address | Keycloak server URI | `https://keycloak.example.com` | +| Domain | Keycloak domain name | `JumpServer` | + +### 2.2 Using Native OIDC + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | Example | +| --- | --- | --- | +| Endpoint Address | OIDC server base Endpoint for discovering various endpoints | `https://oidc.example.com` | +| Authorization Endpoint Address | OIDC Authorization Endpoint | `https://oidc.example.com/realms/JumpServer/protocol/openid-connect/auth/` | +| Token Endpoint Address | OIDC Token Endpoint | `https://oidc.example.com/realms/JumpServer/protocol/openid-connect/token/` | diff --git a/docs/manual/admin/system_settings/authentication_settings/Passkey.en.md b/docs/manual/admin/system_settings/authentication_settings/Passkey.en.md new file mode 100644 index 000000000..bc07bcaf2 --- /dev/null +++ b/docs/manual/admin/system_settings/authentication_settings/Passkey.en.md @@ -0,0 +1,27 @@ +# Passkey Authentication + +## 1 About Passkey + +!!! tip "" + - Click the gear icon in the top-right corner to enter the **System Settings** page, then click **Authentication Settings > Passkey** to open the Passkey configuration page. + - **Passkey** is a passwordless identity authentication technology based on public key encryption that complies with FIDO2 standards (including WebAuthn and CTAP). It supports identity verification through biometrics (such as fingerprint, face), PIN, or security keys, improving security and user experience. + - Some authenticators require JumpServer to enable HTTPS access, otherwise the authentication process may not proceed normally. + +## 2 Configuration Parameters + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | Example | +| --- | --- | --- | +| Passkey | Enable Passkey passwordless authentication | Enable/Disable | +| Service Domain | Complete domain name where Passkey service is available; multiple domains separated by commas | `jumpserver.example.com` | +| Service Name | Passkey service name | `JumpServer` | + +!!! tip "" + - If service domain is not set, it defaults to the request host and matches `DOMAINS` in the `config.txt` file. + +## 3 Operation Instructions + +!!! tip "" + - After configuration is complete, click **Submit** to save settings. diff --git a/docs/manual/admin/system_settings/authentication_settings/Radius.en.md b/docs/manual/admin/system_settings/authentication_settings/Radius.en.md new file mode 100644 index 000000000..da3c0c7bf --- /dev/null +++ b/docs/manual/admin/system_settings/authentication_settings/Radius.en.md @@ -0,0 +1,34 @@ +# RADIUS Authentication + +## 1 About RADIUS + +!!! info "Note: RADIUS authentication is an enterprise feature of JumpServer." + +!!! tip "" + - Click the gear icon in the top-right corner to enter the **System Settings** page, then click **Authentication Settings > Radius** to open the RADIUS configuration page. + - **RADIUS (Remote Authentication Dial In User Service)** is a network access control authentication mechanism based on the RADIUS protocol, providing authentication, authorization, and accounting (AAA) functions. JumpServer supports standard RADIUS authentication. + +## 2 Configuration Parameters + +!!! tip "" + - Click the settings button in the top-right corner + - Navigate to **System Settings > Authentication Settings > Radius** + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | Example | +| --- | --- | --- | +| Radius | Check to enable RADIUS authentication | Enable/Disable | +| Host | RADIUS server IP address or domain name | `172.16.10.180` | +| Port | RADIUS server port number | Default: 1812 | +| Secret | Shared key between JumpServer and RADIUS server. It functions like a password, encrypting sensitive information in RADIUS requests and responses to ensure secure communication | | +| Use radius OTP | Check to enable RADIUS as MFA backend. For more information, see Enable RADIUS MFA Backend below | Enable/Disable | +| Organization | After authentication and creation, user will be added to the selected organization | Default: `DEFAULT` | + +Enable RADIUS MFA Backend + +!!! tip "" + - Configure RADIUS authentication following the RADIUS authentication integration guide. + - In the **Use radius OTP** field, check to enable RADIUS as MFA backend. When user's MFA is enabled, they can select RADIUS authentication type during login. + - Click **Submit**. diff --git a/docs/manual/admin/system_settings/authentication_settings/SAML2.en.md b/docs/manual/admin/system_settings/authentication_settings/SAML2.en.md new file mode 100644 index 000000000..7de60efe0 --- /dev/null +++ b/docs/manual/admin/system_settings/authentication_settings/SAML2.en.md @@ -0,0 +1,58 @@ +# SAML2 Authentication + +## 1 About SAML2 + +!!! info "Note: SAML2 authentication is an enterprise feature of JumpServer." + +!!! tip "" + - Click the gear icon in the top-right corner to enter the **System Settings** page, then click **Authentication Settings > SAML2** to open the SAML2 configuration page. + - **SAML2 (Security Assertion Markup Language 2.0)** is an open standard for securely exchanging identity authentication and authorization data between identity providers (IdP) and service providers (SP). JumpServer authentication supports standard SAML2. + +## 2 Configuration Parameters + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | Example | +| --- | --- | --- | +| SAML2 | Enable SAML2 authentication | Enable/Disable | +| SP Private Key | Upload SP private key file used to sign SAML requests and decrypt IdP responses | | +| SP Certificate | Upload SP certificate file generated from SP private key; used by IdP to verify signatures and encrypt responses | | +| IdP Metadata Address | IdP metadata address URL | `https://saml2.example.com/realms/JumpServer/protocol/saml/descriptor` | +| IdP Metadata XML | Manually enter IdP metadata XML; lower priority than address | | +| Advanced Settings | Advanced parameters for generating SP Metadata; see example below | | +| Mapped Attributes | User attribute mapping; correspondence between SAML2 and JumpServer fields | See JSON example below | +| Organization | After authentication and creation, user will be added to the selected organization | | +| Always Update User Info | When enabled, synchronize user info on every authentication (only name, username, email, phone, comment; groups only on first sync) | | +| Sync Logout | When enabled, logout will also sync SAML2 service logout | | + +!!! tip "" + - SP Private Key and SP Certificate must be used together to ensure SAML2 authentication communication security. SP private key is used for signing and decryption, SP certificate is used for verification and encryption. + - Only one of IdP Metadata Address and XML needs to be filled. If both are filled, the address takes priority. + +!!! tip "" + - Advanced settings example: + +```json +{ + "organization": {}, + "security": {} +} +``` + +!!! tip "" + - SP Metadata provides service provider entity ID, endpoint URLs, certificates, and other information, facilitating IdP configuration. + - You can click **View** below the **SP Certificate** field to get SP Metadata. + +![img](../../../../img/V4_SAML2.png) + +!!! tip "" + - Attribute mapping example: + +```json +{ + "name": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name", + "username": "uid", + "email": "http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress" +} +``` diff --git a/docs/manual/admin/system_settings/authentication_settings/Slack.en.md b/docs/manual/admin/system_settings/authentication_settings/Slack.en.md new file mode 100644 index 000000000..5a5e0db62 --- /dev/null +++ b/docs/manual/admin/system_settings/authentication_settings/Slack.en.md @@ -0,0 +1,43 @@ +# Slack Authentication + +## 1 About Slack + +!!! info "Note: Slack authentication is an enterprise feature of JumpServer." + +!!! tip "" + - Click the gear icon in the top-right corner to enter the **System Settings** page, then click **Authentication Settings > Slack** to open the Slack configuration page. + - **Slack** authentication is an identity authentication mechanism based on the Slack platform, allowing users to securely login to enterprise applications using Slack accounts. JumpServer supports standard Slack authentication. + +## 2 Configuration Parameters + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | Example | +| --- | --- | --- | +| Slack | Check to enable Slack authentication | Enable/Disable | +| Client ID | Slack Client ID, which is the unique identifier of the Slack application used to identify the application during OAuth 2.0 authorization | | +| Client secret | Slack Client secret, which is a secret string associated with the Slack application used to authenticate the application during OAuth 2.0 token exchange | | +| Client bot token | Slack Client bot token, which is an access token granted to the Slack bot, allowing it to interact with the Slack workspace and perform tasks such as sending messages or managing channels | | +| Mapped Attributes | User attribute mapping; key represents JumpServer user attribute name, value corresponds to Slack user attribute name | See example below | +| Organization | After authentication and creation, user will be added to the selected organization | Default: `DEFAULT` | + +Slack User Attribute Example + +!!! tip "" + - The **Mapped Attributes** field is used to set user attribute mapping. The key represents JumpServer user attribute name, and the value corresponds to Slack user attribute name. + +```json +{ + "name": "real_name", + "username": "name", + "email": "profile.email" +} +``` + +## JumpServer Slack URL Description + +| URL Type | Address | Description | +| --- | --- | --- | +| QR Code Login URL | `https://jumpserver.example.com/core/auth/slack/qr/login/` | Slack QR code login entry point | +| QR Code Login Callback URL | `https://jumpserver.example.com/core/auth/slack/qr/login/callback/` | QR code login success callback address | diff --git a/docs/manual/admin/system_settings/authentication_settings/WeCom.en.md b/docs/manual/admin/system_settings/authentication_settings/WeCom.en.md new file mode 100644 index 000000000..92f232a53 --- /dev/null +++ b/docs/manual/admin/system_settings/authentication_settings/WeCom.en.md @@ -0,0 +1,44 @@ +# WeCom Authentication + +## 1 About WeCom Authentication + +!!! info "Note: WeCom authentication is an enterprise feature of JumpServer." + +!!! tip "" + - Click the gear icon in the top-right corner to enter the **System Settings** page, then click **Authentication Settings > WeCom** to open the WeCom configuration page. + - **WeCom Authentication** is an identity authentication method based on WeCom, and JumpServer supports QR code login and enterprise identity binding. + +## 2 Basic Configuration + +!!! tip "" + Detailed parameter descriptions: + +| Parameter | Description | Example | +| --- | --- | --- | +| WeCom | Check to enable WeCom authentication | Enable/Disable | +| Corporation ID | WeCom company ID. Uniquely identifies the enterprise in WeCom; all API requests must include this ID | | +| App agent ID | WeCom application agent ID. Used to identify specific applications in WeCom; each application has a unique agent ID | | +| App secret | WeCom application secret. Used to authenticate the application and obtain access tokens for calling WeCom API | | +| Mapped Attributes | User attribute mapping; key represents JumpServer user attribute name, value corresponds to WeCom user attribute name | See example below | +| Organization | After authentication and creation, user will be added to the selected organization | Default: `DEFAULT` | + +!!! tip "" + - The **Mapped Attributes** field is used to set user attribute mapping. The key represents JumpServer user attribute name, and the value corresponds to WeCom user attribute name. + - WeCom user attribute example: + +```json +{ + "name": "alias", + "username": "userid", + "email": "extattr.attrs[2].value" +} +``` + +## JumpServer WeCom URL Description + +| URL Type | Address | Description | +| --- | --- | --- | +| QR Code Login URL | `https://jumpserver.example.com/core/auth/wecom/qr/login/` | WeCom QR code login entry point | +| QR Code Login Callback URL | `https://jumpserver.example.com/core/auth/wecom/qr/login/callback/` | QR code login success callback address | +| OAuth Login URL | `https://jumpserver.example.com/core/auth/wecom/oauth/login/` | WeCom OAuth login entry point | +| OAuth Login Callback URL | `https://jumpserver.example.com/core/auth/wecom/oauth/login/callback/` | OAuth login success callback address | diff --git a/docs/manual/admin/system_settings/basic_settings.en.md b/docs/manual/admin/system_settings/basic_settings.en.md new file mode 100644 index 000000000..259f870b4 --- /dev/null +++ b/docs/manual/admin/system_settings/basic_settings.en.md @@ -0,0 +1,12 @@ +# Basic Settings + +## 1 Feature Overview +!!! tip "" + - Click the settings icon in the top right corner of the page to enter the **System Settings** page, then click **Basic Settings** to access the basic settings page. + - You can edit basic information, including the current site URL and navigation bar link configuration. + +## 2 Basic Information +!!! tip "" + - On this page, you can configure the current site URL (users can access the bastion host through external links, such as email, so you can fill in a domain name or IP here). + - Supports configuring navigation bar links. +![V4_systemsetting_basic](../../../img/V4_systemsetting_basic.png) diff --git a/docs/manual/admin/system_settings/components.en.md b/docs/manual/admin/system_settings/components.en.md new file mode 100644 index 000000000..a5d1224e9 --- /dev/null +++ b/docs/manual/admin/system_settings/components.en.md @@ -0,0 +1,41 @@ +# Component Settings +!!! tip "" + - Click the settings icon in the top right corner of the page to enter the **System Settings** page, then click **Component Settings** to access the component settings page. + - The component settings page mainly configures JumpServer component information. + +## 1 Basic Settings +!!! info "Note: Razor component and Magnus component are enterprise edition features" + +!!! tip "" + - Detailed parameters: + +| Parameter Name | Description | Example or Default | +|------------------|----------------------------------------------------------------------|--------------| +| Component Registration | Select the component registration method. Auto registration (valid 5 mins after JumpServer startup), enable, or disable. When deploying remote application publishing or extending JumpServer nodes, select enable to ensure component registration succeeds. | Enable | +| Client Connection | Allow connecting to KoKo component through SSH client | Enable | +| Password | Allow users to log in to KoKo component through password authentication | Enable | +| SSH Public Key | Allow users to log in to KoKo component through public key authentication | Enable | +| Asset List Sorting | Select asset list sorting method, sort by name or address | Name | +| Assets Per Page | Set the number of assets displayed per page in the client connection command line type asset list | 10 | +| Razor | Enable Razor component for RDP client connection | Enable | +| Magnus | Enable Magnus component for database local client connection (e.g., Navicat, DBeaver, etc.) | Enable | + + + +## 2 Component List +!!! tip "" + - The component list page allows you to view and manage all component registration information for JumpServer. + - Click the **button** of a component to update the component's commands, storage, and recording storage. Session recordings are stored locally on the server by default; session commands are stored in the database by default. Here you can change session recording and session command storage to external storage. If you select **null**, no storage will be performed. + +## 3 Component Monitoring +!!! tip "" + - The component monitoring page allows you to view the load status and session count of all JumpServer components. + +## 4 Service Endpoints + +!!! tip "" + - The service endpoints page mainly contains settings for access entry points. Service endpoints are the addresses (ports) for users to access services. When users connect to assets, they select service endpoints based on endpoint rules and asset tags as access entry points to establish connections, achieving distributed asset connection. + +## 5 Endpoint Rules +!!! tip "" + - For service endpoint selection strategy, currently two methods are supported: 1. Specify endpoints based on endpoint rules (current page); 2. Select endpoints through asset tags, with the fixed tag name being "endpoint" and the value being the endpoint name. The two methods prioritize tag matching first, since IP ranges may conflict. The tag method serves as a supplement to the rules. In endpoint rules, you set which IP ranges correspond to which service endpoints, and it also supports matching by domain. diff --git a/docs/manual/admin/system_settings/feature_settings.en.md b/docs/manual/admin/system_settings/feature_settings.en.md new file mode 100644 index 000000000..62b902814 --- /dev/null +++ b/docs/manual/admin/system_settings/feature_settings.en.md @@ -0,0 +1,58 @@ +# Feature Settings + +!!! tip "" + - Enter the **System Settings** page by clicking the gear icon in the top-right corner, then click **Feature Settings** to open the feature settings page. + +## 1 Announcements +!!! tip "" + - Click **Announcements** at the top of the page to enter the announcement settings page. + - This page allows you to customize whether to enable announcement functionality and set announcement content to be displayed globally on the JumpServer page. +![V4_systemsetting_feature1](../../../img/V4_systemsetting_feature1.png) + +!!! tip "" + - The effect after enabling announcements is shown below. +![V4_systemsetting_feature2](../../../img/V4_systemsetting_feature2.png) + +## 2 Tickets +!!! tip "" + - Click **Tickets** at the top of the page to enter the ticket settings page. + - You can customize whether to enable the ticket feature for users to request resource authorizations through tickets. +![V4_systemsetting_feature3](../../../img/V4_systemsetting_feature3.png) + +!!! tip "" + - The effect after enabling tickets is shown below. +![V4_systemsetting_feature4](../../../img/V4_systemsetting_feature4.png) + +## 3 Job Center +!!! tip "" + - Click **Job Center** at the top of the page to enter the job center settings page. + - The batch command execution option determines whether to allow users to execute batch commands in **Workbench > Job Center**. + - The job center command blacklist settings prevent certain commands from being used in batch commands. +![V4_systemsetting_feature5](../../../img/V4_systemsetting_feature5.png) + +## 4 Account Storage +!!! info "Note: Account storage is an Enterprise edition feature." + +!!! tip "" + - Click **Account Storage** at the top of the page to enter the account storage settings page. + - Account secrets support integration with HashiCorp Vault third-party secret storage system. Users need to modify the `VAULT_ENABLED = true` parameter in the `config.txt` configuration file and configure the `VAULT_BACKEND = [local/hcp/azure/aws]` parameter according to the storage engine, then return to the page to configure. + - Perform data synchronization, which is one-way and only syncs from the local database to the remote Vault. After synchronization completes, the local database no longer stores passwords; please backup your data. + - Restarting the service is required after modifying the Vault configuration. +![V4_systemsetting_feature6](../../../img/V4_systemsetting_feature6.png) + +## 5 Smart Q&A + +!!! tip "" + - Click **Smart Q&A** at the top of the page to enter the Smart Q&A settings page. + - Smart Q&A supports integration with ChatGPT, Deepseek, and custom model services (custom model feature is available in v4.10.14 and above). After enabling, you can start the chat AI feature for smart Q&A. + - Fill in the base address and API Key of the chat service, click **Save**, then click **Test**. After successful connection test, you can start chatting with the smart assistant. +![V4_systemsetting_feature7](../../../img/V4_systemsetting_feature7.png) + +## 6 Virtual Applications +!!! info "Note: Virtual applications are an Enterprise edition feature." + +!!! tip "" + - Click **Virtual Applications** at the top of the page to enter the virtual applications settings page. + - JumpServer supports using Linux systems as the runtime carrier for remote application functionality. Enable virtual application functionality based on Linux systems on this page. + - For usage configuration, see [Virtual Applications Configuration](virtual_apps.md). +![V4_systemsetting_feature8](../../../img/V4_systemsetting_feature8.png) diff --git a/docs/manual/admin/system_settings/licenses.en.md b/docs/manual/admin/system_settings/licenses.en.md new file mode 100644 index 000000000..1e417b308 --- /dev/null +++ b/docs/manual/admin/system_settings/licenses.en.md @@ -0,0 +1,8 @@ +# Licenses +!!! tip "" + - Enter the **System Settings** page by clicking the gear icon in the top-right corner, then click **Licenses** to open the licenses page. + - Click the **Licenses** button on the left side of the page to enter the licenses page. This page allows you to import FIT2CLOUD Enterprise License to use enterprise features, and you can view the number of asset authorizations and the expiration time of JumpServer Enterprise License. +!!! warning "Non-enterprise installation packages cannot import License." +!!! tip "" + - You can import licenses by clicking the **Import** button. +![V4_lisence_01.png](../../../img/V4_lisence_01.png) diff --git a/docs/manual/admin/system_settings/notification_settings.en.md b/docs/manual/admin/system_settings/notification_settings.en.md new file mode 100644 index 000000000..99ee32006 --- /dev/null +++ b/docs/manual/admin/system_settings/notification_settings.en.md @@ -0,0 +1,61 @@ +# Notification Settings + +!!! tip "" + - Enter the **System Settings** page by clicking the gear icon in the top-right corner, then click **Notification Settings** to open the notification settings page. + +## 1 Email Settings +!!! tip "" + - The email settings interface primarily configures the sender email information for sending emails such as user password setup emails, dangerous command emails, authorization expiration emails, etc. to JumpServer user mailboxes. +![V4_systemsetting_notification_settings1](../../../img/V4_systemsetting_notification_settings1.png) + +!!! tip "Parameter Description" +| Parameter | Description | +|-----------|-------------| +| Protocol | Protocol used by the email service | +| Host | Email server address | +| Port | Port used by the email server | +| Account | Username to log in to the email server | +| Password | Password to log in to the email server | +| Sender | Email address of the sender | +| Use SSL | Whether to use implicit TLS connection when communicating with SMTP server | +| Use TLS | Whether to use TLS connection when communicating with SMTP server | +| Email Template | Template for sending emails, including email title prefix and email content | +| Recipient | Test mailbox address for testing email server connectivity | + +## 2 SMS Settings +!!! info "Note: SMS service is a JumpServer Enterprise edition feature." + +### 2.1 Overview +!!! tip "" + - You can set SMS MFA authentication method (currently supports Alibaba Cloud, Tencent Cloud, Huawei Cloud, CMPP V2.0, and custom integration). + - JumpServer also supports using SMS to recover user passwords. Administrators need to enable SMS service, and user information needs to have a phone number configured. +![V4_systemsetting_notification_settings2](../../../img/V4_systemsetting_notification_settings2.png) + +### 2.2 Configuration Description +!!! tip "" + - Select the corresponding SMS service provider and fill in the authentication information from the service provider platform. Click the **Test** button to test whether the configuration is correct. +![V4_systemsetting_notification_settings3](../../../img/V4_systemsetting_notification_settings3.png) +!!! tip "SMS Configuration Template Example" + - Your JumpServer verification code is: ${code}, valid within 1 minute. Do not share! + +### 2.3 User-side Configuration +!!! tip "" + - Click your avatar - Personal Information to configure your personal phone number in the phone section. +![V4_systemsetting_notification_settings4](../../../img/V4_systemsetting_notification_settings4.png) + +!!! tip "" + - Click the MFA authentication settings button to open the settings page. + - Click the Enable MFA button, then click the Enable SMS button to use SMS authentication. +![V4_systemsetting_notification_settings5](../../../img/V4_systemsetting_notification_settings5.png) +![V4_systemsetting_notification_settings6](../../../img/V4_systemsetting_notification_settings6.png) + +## 3 Message Subscriptions +### 3.1 Overview +!!! tip "" + - You can set the recipients of JumpServer platform monitoring messages. + - You can set the sending method for monitoring messages (in-site and email). +![V4_systemsetting_notification_settings7](../../../img/V4_systemsetting_notification_settings7.png) +### 3.2 Set Message Recipients +!!! tip "" + - Configure message recipients to receive platform monitoring notifications. +![V4_systemsetting_notification_settings8](../../../img/V4_systemsetting_notification_settings8.png) diff --git a/docs/manual/admin/system_settings/organization_manage.en.md b/docs/manual/admin/system_settings/organization_manage.en.md new file mode 100644 index 000000000..77a949287 --- /dev/null +++ b/docs/manual/admin/system_settings/organization_manage.en.md @@ -0,0 +1,18 @@ +# Organization Management + +!!! info "Note: Organization management is a JumpServer Enterprise edition feature." + +## 1 Overview +!!! tip "" + - Enter the **System Settings** page by clicking the gear icon in the top-right corner, then click **Organization Management** to open the organization management page. + - JumpServer supports organization-based management methods, enabling authorization administrators to create and view operational audit information for different organizational environments according to company organizational structure, including administrators, users, user groups, assets, domains, accounts, labels, permission management, etc. +![V4_systemsetting_organization_manage1](../../../img/V4_systemsetting_organization_manage1.png) + +## 2 Create Organization +!!! tip "" + - Click the **Create** button to create a new organization and enter the organization name and notes. + - Click the **Settings** button to set the display name of the global organization. +![V4_systemsetting_organization_manage2](../../../img/V4_systemsetting_organization_manage2.png) +![V4_systemsetting_organization_manage3](../../../img/V4_systemsetting_organization_manage3.png) + +!!! warning "Updates and deletions of roles, assets, accounts and other information within organizations should be performed within their respective organizations." diff --git a/docs/manual/admin/system_settings/overview.en.md b/docs/manual/admin/system_settings/overview.en.md new file mode 100644 index 000000000..e1fe37831 --- /dev/null +++ b/docs/manual/admin/system_settings/overview.en.md @@ -0,0 +1,8 @@ +# Overview + +## 1 Overview +!!! tip "" + - Enter the **System Settings** page by clicking the gear icon in the top-right corner. + - System Settings is the operation entry point for global JumpServer settings. Through System Settings, you can configure various types of system parameters such as JumpServer roles, platforms, remote applications, security, etc. + +![V4_systemsetting_overview](../../../img/V4_systemsetting_overview.png) diff --git a/docs/manual/admin/system_settings/platforms.en.md b/docs/manual/admin/system_settings/platforms.en.md new file mode 100644 index 000000000..b866fdb7f --- /dev/null +++ b/docs/manual/admin/system_settings/platforms.en.md @@ -0,0 +1,63 @@ +# Platform List + +!!! warning "Note: Starting from v4.9, JumpServer platform-related settings have been moved to System Settings" + +## 1 Overview +!!! tip "" + - Enter the **System Settings** page by clicking the gear icon in the top-right corner, then click **Platform List** to open the platform list page. + - The platform list is selectable when creating assets. Users can select different system types such as Linux, Windows, etc. when creating assets. + - At the same time, you can create new platform types by selecting a specified base platform, which can then be specified as the new platform type in asset creation. +![V4_platforms_1](../../../img/V4_platforms_1.png) + +## 2 Create Asset Platform +!!! tip "" + - Click the **Create** button on the platform list page and fill in the asset platform information to create a new asset platform, using Linux as an example. +![V4_platforms_2](../../../img/V4_platforms_2.png) +![V4_platforms_3](../../../img/V4_platforms_3.png) + +!!! tip "" + - Detailed parameter descriptions: + +| Parameter | Description | +|-----------|-------------| +| Name | The name of the asset platform | +| Type | The type of asset platform; different system types determine different encodings and automation methods | +| Encoding | The encoding method for the asset platform, selectable between "UTF-8" or "GBK" | +| Enable Domain | Whether to enable domain; some platform types cannot enable domain meaning those platform types do not support domain functionality | +| Supported Protocols | Set the protocols supported by the asset platform; default protocols for each platform cannot be deleted; default port numbers for protocols can be modified | + +!!! tip "" + - Account switching parameter description: + +| Option | Description | +|--------|-------------| +| Enable Account Switching | Enable account switching with supported account switching methods such as `sudo su -` and `su -` | +| Disable Account Switching | Disable account switching functionality; some asset platforms do not support account switching meaning those platforms do not support account switching | + +!!! tip "" + - Automation parameter description (enabled state); disabled means automation tasks are closed: + +| Parameter | Description | +|-----------|-------------| +| Ansible Configuration | Ansible connection and other information configuration; generally not modified | +| Enable Asset Probing | Whether to enable asset probing for connectivity detection | +| Asset Probing Method | Set the asset probing method | +| Collect Asset Info | Whether to enable asset information collection for hardware info, etc. | +| Information Collection Method | Set the information collection method | +| Enable Account Password Change | Whether to enable account password change | +| Account Password Change Method | Set the account password change method | +| Enable Account Push | Whether to enable account push | +| Account Push Method | Set the account push method; can be modified in account push | +| Enable Account Validation | Whether to enable account validation | +| Account Validation Method | Set the account validation method | +| Enable Account Collection | Whether to enable account collection functionality | +| Account Collection Method | Set the account collection method | + + +## 3 Custom SFTP Directory Path +!!! tip "" + - The default SFTP directory path is `/tmp`, and custom directories are supported. + - Click the **Create** button on the platform list page, add the SFTP protocol, then click the **gear** button behind the configuration. + - Customize the SFTP root directory modification. +![V4_platforms_4](../../../img/V4_platforms_4.png) +![V4_platforms_5](../../../img/V4_platforms_5.png) diff --git a/docs/manual/admin/system_settings/remote_apps.en.md b/docs/manual/admin/system_settings/remote_apps.en.md new file mode 100644 index 000000000..b98047564 --- /dev/null +++ b/docs/manual/admin/system_settings/remote_apps.en.md @@ -0,0 +1,70 @@ +# Remote Applications +!!! warning "Note: Community edition only supports Web GUI for remote applications; local client connection (MSTSC) is an Enterprise edition feature." +## 1 Overview +!!! tip "" + - Enter the **System Settings** page by clicking the gear icon in the top-right corner, then click **Remote Applications** to open the remote applications page. + - RemoteApp is a service functionality integrated by Microsoft in Windows Server 2008 and later systems, allowing users to access remote desktops and programs through Remote Desktop without requiring clients to install systems and applications locally. + +![img](../../../img/V4_RemoteApp1.png) + +## 2 Application Publisher +!!! tip "" + - RemoteApp functionality requires preparing an application publisher environment. + - The application publisher is the runtime carrier for running Web page assets or programs using remote applications like Navicat to connect to databases. + +### 2.1 System Requirements +!!! tip "" + - The specific system requirements for the application publisher are as follows: + +| Configuration | Minimum Requirement | Description | +|-----------|-----------|------| +| Operating System | Windows Server 2019 | Recommended to use Windows Server 2019 | +| CPU | 4 cores | At least 4 CPU cores | +| Memory | 8 GB | At least 8 GB RAM | +| Remote Management Protocol | WinRM or OpenSSH | One of these protocols must be installed and correctly configured | +| RDS License | Installed and activated | Remote Desktop Services license must be valid; Windows Server defaults to 120-day trial | +| Network Connection | Able to access JumpServer service via network (HTTPS/HTTP) | Required for registration and application installation | + +### 2.2 Create Application Publisher +!!! tip "" + - Click the **Create** button on the application publisher page to create a new application publisher. + +![img](../../../img/V4_RemoteApp2.png) + +!!! tip "" + - Deploying an application publisher through OpenSSH protocol requires installing OpenSSH, which can be obtained from the JumpServer page - **Web Terminal** > **Help** > **Download**. + +#### WinRM (Recommended) + +!!! note "" + WinRM is a remote management service launched by Microsoft that can be quickly enabled using the `winrm quickconfig` command in PowerShell or CMD with an administrator account. + +!!! tip "" + - Simply add the WinRM protocol when creating an application publisher. If SSH protocol also exists, JumpServer will prioritize SSH. + +![remoteapp18](../../../img/V4_RemoteApp7.png) + +#### OpenSSH + +!!! tip "" + - Deploying an application publisher through OpenSSH protocol requires first installing the OpenSSH protocol component. + +![V4_RemoteApp3](../../../img/V4_RemoteApp3.png) + +!!! tip "" + - After uploading the OpenSSH installation package to the application publisher desktop, double-click to install. + +![V4_RemoteApp4](../../../img/V4_RemoteApp4.png) + +!!! tip "" + - Detailed parameter descriptions: + +| Parameter | Description | +| ------- | --------------------- | +| Name | The name of the remote application publisher for identification | +| IP/Hostname | IP information of the remote application publisher | +| Protocol Group | Protocol family and port supported by the remote application publisher | +| Account List | Connection account information for the remote application publisher, such as **Administrator** user; at least one privileged account in the Administrator group is needed for managing remote applications | +| Auto Create Account | Accounts created by this option are used to connect to published applications | +| Create Account Count | Number of public accounts to create | +| Core Service Address | Communication address between the application publisher's Agent and JumpServer Core component service | diff --git a/docs/manual/admin/system_settings/role_list.en.md b/docs/manual/admin/system_settings/role_list.en.md new file mode 100644 index 000000000..63572a9fe --- /dev/null +++ b/docs/manual/admin/system_settings/role_list.en.md @@ -0,0 +1,54 @@ +# Role List + +!!! warning "Note: Starting from v4.9, JumpServer role-related settings have been moved to System Settings" + +## 1 Overview +!!! tip "" + - Click the **Gear** icon in the top-right corner to open the **System Settings** page. + - Click **System Settings > Role List** to open the **Role List** page. + - The system default roles are System Administrator, System Auditor, User and System Components; organization roles default to Organization Administrator, Organization Auditor, Organization User. Default roles cannot be deleted or updated. + +## 2 Create Role +!!! tip "" + - Click the **Create** button in the top-left of the **Role List** page to open the role creation page. + - Both system roles and organization roles can be created. +![role_list_01](../../../img/v4_role_list_01.png) +!!! tip "" + - After successfully creating a role, enter the new role's detail page where you can set permissions for the role. + - As shown below, the right portion shows role permission settings. After updating settings according to requirements, click the **Update** button to submit. +![role_list_02](../../../img/v4_role_list_02.png) + +## 3 Role Import/Export +!!! tip "" + - Roles support import for creation and export of existing roles in xlsx and csv table formats. + - For the first import, click the **Import** button to download a template, fill in information as prompted, then import. +![role_list_03](../../../img/v4_role_list_03.png) + +## 4 Role Details +!!! tip "" + - Click a role name on the **Role List** page to open the role detail page. + - The role detail page contains role basic information, role permissions, authorized users, and role activity logs. +![role_list_04](../../../img/v4_role_list_04.png) +!!! tip "Detailed parameter descriptions" +| Parameter | Description | +|-----------|-------------| +| Basic Settings | The basic settings page displays detailed role information including name, whether built-in, creator, etc. | +| Permissions | This option is used to set permissions for the current role and which features can be used | +| Authorized Users | This page binds roles with users, granting users the permissions of that role | +| Activity | This page displays activity logs for the current role | + +## 5 Update Role +!!! tip "" + - When you need to update a role's information, click the **Edit** button next to the role on the **Role List** page. +![role_list_05](../../../img/v4_role_list_05.png) + +## 6 Clone Role +!!! tip "" + - Click the **...** button next to the role and select **Copy** to open the role creation interface. After modifying relevant information and submitting, modify role permissions to complete cloning. +![role_list_06](../../../img/v4_role_list_06.png) + +## 7 Delete Role +!!! tip "" + - System default roles cannot be deleted; non-built-in roles can be deleted. + - Click the **Delete** button next to the role to delete it. +![role_list_07](../../../img/v4_role_list_07.png) diff --git a/docs/manual/admin/system_settings/security.en.md b/docs/manual/admin/system_settings/security.en.md new file mode 100644 index 000000000..93cbebd80 --- /dev/null +++ b/docs/manual/admin/system_settings/security.en.md @@ -0,0 +1,71 @@ +# Security Settings + +!!! tip "" + - Click the gear icon in the top-right corner to enter the **System Settings** page, then click **Security Settings** to open the security settings page. + - The security settings page mainly configures security-related information for JumpServer, including authentication security and password validation rules. + +## 1 Authentication Security +![V4_security_01.png](../../../img/V4_security_01.png) +!!! tip "" + - Detailed parameter descriptions: + + | Parameter | Description | + | :--- | :--- | + | Enable Login Captcha | Enable login captcha to prevent robot logins. | + | Enable Login Additional Code | Password and additional code are sent together to third-party authentication system for verification, such as some third-party authentication systems that require password + 6-digit number to complete authentication. | + | Automatically Disable Inactive Users (Days) | Set a preset time; users who have not logged in to JumpServer within this time will be automatically disabled. | + | Remote Login Notification | Based on login IP, determine if it belongs to common login locations; if not, send remote login alert email to user's mailbox. | + | Globally Enable MFA Authentication | You can set to disable MFA, enable MFA for all users, or enable only for administrators. When MFA is globally enabled, individual users cannot disable MFA verification. | + | Third-Party Enable MFA | Support MFA authentication for users with OIDC, CAS, SAML2 authentication methods. | + | MFA Validity Period | After MFA verification when viewing account passwords, no need to verify again within the validity period. | + | OTP Name After Scanning | Display name of dynamic code in software after binding MFA. | + | OTP Delayed Valid Times | Number of valid times for OTP delay. | + + +## 2 Login Restrictions +![V4_security_02.png](../../../img/V4_security_02.png) +!!! tip "" + - Detailed parameter descriptions: + + | Parameter | Description | + | :--- | :--- | + | Limit User Login Failed Attempts | Maximum number of password errors for user login; user will be locked for a period after reaching this limit. | + | Disable User Login Interval | Duration user is locked. | + | Limit IP Login Failed Attempts | Maximum login failures for an IP; login will be blocked for a period after reaching this limit. | + | Disable IP Login Interval | Duration IP is locked. | + | IP Login Whitelist | IPs allowed to login to the bastion host. | + | IP Login Blacklist | IPs not allowed to login to the bastion host. | + | Locked IPs | IPs locked after exceeding set login failure attempts. | + | Only One Device Login | Only allow users to login on one device. Next device login will force off previous login. | + | Only Existing Users Login | Only allow users existing in JumpServer user list to login. | + | Only Login from User Source | Only allow users to login from sources listed in the user list. | + +## 3 Password Security +![V4_security_03.png](../../../img/V4_security_03.png) +!!! tip "" + - Detailed parameter descriptions: + + | Parameter | Description | + | :--- | :--- | + | User Password Expiration Time (Days) | Interval in days users must forcibly update passwords. Unit: days. If user does not update password within this period, user password will expire and become invalid; password expiration reminder email will be automatically sent by system daily within 5 days before expiration. | + | Cannot Set Last N Passwords | When user resets password, cannot use the last N passwords used for this user. | + | Minimum Password Length | Set the minimum length supported for user passwords. | + | Admin Password Minimum Length | Set the minimum length supported for administrator passwords. | + | Must Contain Uppercase Characters | Password must contain uppercase characters. | + | Must Contain Lowercase Characters | Password must contain lowercase characters. | + | Must Contain Numbers | Password must contain numeric characters. | + | Must Contain Special Characters | Password must contain special characters such as #$@% etc. | + +## 4 Session Security +![V4_security_04.png](../../../img/V4_security_04.png) +!!! tip "" + - Detailed parameter descriptions: + + | Parameter | Description | + | :--- | :--- | + | Enable Watermark | Management interface, sessions and recordings will include watermark information of bastion host users accessing assets. RDP client-mode connections do not support watermarks. | + | Session Sharing | When enabled, allows users to share connected asset sessions via URL to others for collaborative work. | + | Session Expires When Browser Closes | Whether to terminate session when user closes browser. | + | Allow Users to View Asset Session Information | When user connects to asset, account selection dialog displays current number of active sessions for asset (RDP protocol only). | + | Connection Maximum Idle Time (Minutes) | Asset will auto-disconnect when idle time reaches this configuration. | + | Session Connection Maximum Time (Hours) | Asset connection session will auto-disconnect after reaching this time. | diff --git a/docs/manual/admin/system_settings/storage.en.md b/docs/manual/admin/system_settings/storage.en.md new file mode 100644 index 000000000..74715b477 --- /dev/null +++ b/docs/manual/admin/system_settings/storage.en.md @@ -0,0 +1,21 @@ +# Storage Settings + +!!! tip "" + - Click the **Gear** icon in the top-right corner to open the **System Settings** page. + - Click **System Settings > Storage Settings** to open the **Storage Settings** page. + - The storage settings page mainly configures settings for JumpServer recording storage, account backup, and command storage. + +## 1 Object Storage + +!!! tip "" + - The object storage page allows you to customize where JumpServer stores session recordings when connecting to assets. Currently supported external recording storage includes Amazon S3 cloud storage, Ceph, Swift, OSS, Azure, OBS, COS. + - SFTP storage only supports account backup server. + +!!! info "Note: Account backup and SFTP storage are enterprise features" + +## 2 Command Storage + +!!! tip "" + - The command storage page allows you to change where JumpServer stores session command logs when connecting to assets. By default, asset session command logs are stored in JumpServer's database. Currently supported external command storage includes Elasticsearch. + - Elasticsearch host format: `http://es_user:es_password@es_host:es_port`. + - If creating index by date is enabled, the input value will be used as the index prefix. diff --git a/docs/manual/admin/system_settings/system_tasks.en.md b/docs/manual/admin/system_settings/system_tasks.en.md new file mode 100644 index 000000000..39b9a4edc --- /dev/null +++ b/docs/manual/admin/system_settings/system_tasks.en.md @@ -0,0 +1,48 @@ +# System Tasks + +!!! tip "" + - Click the **Gear** icon in the top-right corner to open the **System Settings** page. + - Click **System Settings > System Tasks** to open the **System Tasks** page. + +## Task List + +!!! tip "" + - JumpServer supports using Ansible and other technologies to implement automated task execution. The system tasks page displays task execution logs and the status of Celery component and historical records of executed tasks. +![V4_system_task_01.png](../../../img/V4_system_task_01.png) + +!!! tip "" + - This page displays all automated tasks, including account backup plans, account push, asset connectivity checks, email sending automated tasks, etc. + - Click on an automated task name to enter the task detail page where you can view task details and execution history. + +!!! tip "" + - Click the **Task Monitor** button in the top-left of the page to view related status of JumpServer's backend batch task component. +![V4_system_task_02.png](../../../img/V4_system_task_02.png) + +!!! tip "" + - Click on task status in the upper section of the page to view logs of successful tasks or logs of failed tasks, and check related information of backend celery component and ansible service. +![V4_system_task_03.png](../../../img/V4_system_task_03.png) + +!!! tip "" + - Click on processed count and success total to display detailed task information. +![V4_system_task_04.png](../../../img/V4_system_task_04.png) + +## Periodic Cleanup + +!!! tip "" + - Click the **Periodic Cleanup** button to enter the periodic cleanup settings page where you can configure scheduled cleanup cycles for login, task, operation, upload/download logs, and database records audit tasks, reducing pressure on server storage. + - The configuration on this page mainly controls locally saved records; when recordings and logs are stored in external storage, this page configuration does not affect them. +![V4_system_task_05.png](../../../img/V4_system_task_05.png) + +!!! tip "" + Detailed parameter descriptions: + + | Parameter | Description | + | --- | --- | + | Login Logs | Login logs mainly record JumpServer user login information, including username, type, Agent, login IP address, login location, and login date. | + | Task Logs | Task logs mainly record information about automated tasks such as batch commands. | + | Operation Logs | Operation logs mainly record user operations on assets, operation time, and resource type and remote address of operations. | + | Upload/Download | Upload/download mainly records operation logs left by users when performing FTP upload and download. | + | Session Logs Save Time | Session logs mainly record session logs generated by logging into assets through JumpServer, including recordings and command logs. | + | Activity Records | Activity records mainly record operation information on asset, authorization, account or task detail pages. | + | Job Center Execution History | Job center mainly records historical information of job center task execution, including quick commands and jobs. | + | Cloud Sync Records | Cloud sync records mainly record information about executing cloud sync tasks. | diff --git a/docs/manual/admin/system_settings/tools.en.md b/docs/manual/admin/system_settings/tools.en.md new file mode 100644 index 000000000..61ff53688 --- /dev/null +++ b/docs/manual/admin/system_settings/tools.en.md @@ -0,0 +1,7 @@ +# System Tools + +!!! tip "" + - Click the **Gear** icon in the top-right corner to open the **System Settings** page. + - Click **System Settings > System Tools** to open the **System Tools** page. + - This page contains system tools including ping, telnet, Nmap, Tcpdump, and Traceroute, allowing users to detect network connections between assets and JumpServer service. +![V4_tools_01.png](../../../img/V4_tools_01.png) diff --git a/docs/manual/admin/system_settings/virtual_apps.en.md b/docs/manual/admin/system_settings/virtual_apps.en.md new file mode 100644 index 000000000..33df6fc6a --- /dev/null +++ b/docs/manual/admin/system_settings/virtual_apps.en.md @@ -0,0 +1,57 @@ +# Virtual Applications + +!!! info "Note: Virtual Applications are an enterprise feature." + +## 1 Feature Overview + +!!! tips "" + - VirtualApp (Virtual Application) is a remote application feature launched by JumpServer based on Linux graphical operating system, originally designed for Xinchuang system scenarios. + - Panda is also known as Application Provider, a JumpServer component used to manage VirtualApp. + - Through virtual applications, you can publish Web, database, and other assets. + +## 2 Feature Enable + +### 2.1 Enable Virtual Applications + +!!! info "" + - Check Virtual Applications on System Settings → Feature Settings → Virtual Applications page and submit. +![img](../../../img/v4_virtualapp1.png) + + +### 2.2 Change Configuration File + +!!! info "" + - Login to the server where JumpServer runs as root or other privileged account. + - Modify or add this line of configuration, entering the IP address of the Linux server providing virtual application service. + +``` sh +vim /opt/jumpserver/config/config.txt +PANDA_HOST_IP=IP +``` + +!!! info "" + - After modification, save and execute the following command to restart JumpServer. + +``` sh +jmsctl restart +``` + +### 2.3 View Virtual Application Status + +!!! info "" + - Go to System Settings → Remote Applications → Application Provider page to view running Panda components. Click on component name to view details. + - Panda will retrieve uploaded virtual applications every 5 minutes. +![img](../../../img/v4_virtualapp2.png) + +### 2.4 Upload Virtual Application + +!!! info "" + - Go to System Settings → Remote Applications → Virtual Applications page to see two default applications: Chrome Browser and Firefox Browser. + - You can click the Upload button to upload self-developed applications. +![img](../../../img/v4_virtualapp3.png) + +## 3 Feature Usage + +!!! info "" + - After configuration is complete, create a Website asset and use Web Terminal to select virtual application mode for connection. +![img](../../../img/v4_virtualapp4.png) diff --git a/docs/manual/admin/workbench/job_center/adhoc.en.md b/docs/manual/admin/workbench/job_center/adhoc.en.md new file mode 100644 index 000000000..697d0c9cf --- /dev/null +++ b/docs/manual/admin/workbench/job_center/adhoc.en.md @@ -0,0 +1,26 @@ +# Quick Commands + +!!! warning "Note: In v4.0, Job Center is disabled by default. System administrators need to enable it at **System Settings > Feature Settings > Job Center**." + +!!! tip "" + - Click the **Workbench** button on the navigation bar to open the **Workbench** page. + - Click **Job Center > Quick Commands** to open the **Quick Commands** page. + - Quick Commands allows batch command execution on assets that users have permission for. Select assets to execute quick commands in the asset tree, and select account information, timeout settings, etc. +![v4_quick_command_1](../../../../img/v4_quick_command_1.png) + +!!! tip "" + - Detailed module description: + + | No. | Name | Description | + | --- | --- | --- | + | 1 | Asset Tree | Select assets to execute commands on. | + | 2 | Run | Button to run commands. | + | 3 | Run User | User on target asset running the command. | + | 4 | Account Policy | ● Ignore Current Asset
    ● Prefer Privileged Accounts
    ● Privileged Accounts Only | + | 5 | Language | Currently supported language types: Shell, PowerShell, Raw, Python, MySQL, PostgreSQL, SQL Server. | + | 6 | Timeout (Sec) | Command execution timeout; currently supports: 10, 30, 60 seconds. | + | 7 | Run Path | Directory for executing the quick command. | + | 8 | Open Command/Save Command | Open commands from template management module/Save current command to template management module. | + | 9 | Command Input Area | Command to execute. | + | 10 | Result Output Area | Results of command execution. | + | 11 | Clear Screen & Scroll | Clear all command execution results. | diff --git a/docs/manual/admin/workbench/job_center/execute_history.en.md b/docs/manual/admin/workbench/job_center/execute_history.en.md new file mode 100644 index 000000000..6e4e4d86d --- /dev/null +++ b/docs/manual/admin/workbench/job_center/execute_history.en.md @@ -0,0 +1,7 @@ +# Execution History + +!!! tip "" + - Click the **Workbench** button on the navigation bar to open the **Workbench** page. + - Click **Job Center > Execution History** to open the **Execution History** page. + - The execution history page mainly records history of tasks in the Job Center module. You can view task execution details and specific output information on this page. +![v4_execute_history_1](../../../../img/v4_execute_history_1.png) diff --git a/docs/manual/admin/workbench/job_center/jobs_management.en.md b/docs/manual/admin/workbench/job_center/jobs_management.en.md new file mode 100644 index 000000000..7a83df140 --- /dev/null +++ b/docs/manual/admin/workbench/job_center/jobs_management.en.md @@ -0,0 +1,22 @@ +# Jobs Management + +!!! tip "" + - Click the **Workbench** button on the navigation bar to open the **Workbench** page. + - Click **Job Center > Jobs Management** to open the **Jobs Management** page. + - Jobs Management supports creating two types of job tasks: commands and Playbooks. Users can set jobs to run periodically or manually, enabling automated operation and maintenance. + +## 1 Create Job + +!!! tip "" + - Using Playbook-type job task as an example. Before creating a Playbook job, you need to pre-create a Playbook template in the `Template Management` feature. Click the `Job Center` dropdown menu, select `Jobs Management` to enter the jobs management page, and click the `Create` button to create a Playbook job. + +!!! tip "" + - Enter the Jobs Management - Playbook page, click the `Create` button to create a new Playbook job + - In the **Playbook Parameters** section, select a pre-created Playbook template; these templates need to be created and configured in `Template Management` beforehand. +![v4_activity_manage_1](../../../../img/v4_activity_manage_1.png) + +## 2 Execute Job + +!!! tip "" + - Click the `Execute` button after a created Playbook job entry to start Playbook job execution. +![v4_activity_manage_2](../../../../img/v4_activity_manage_2.png) diff --git a/docs/manual/admin/workbench/job_center/templates_management.en.md b/docs/manual/admin/workbench/job_center/templates_management.en.md new file mode 100644 index 000000000..bbcf395fa --- /dev/null +++ b/docs/manual/admin/workbench/job_center/templates_management.en.md @@ -0,0 +1,34 @@ +# Templates Management + +!!! tip "" + - Click the **Workbench** button on the navigation bar to open the **Workbench** page. + - Click **Job Center > Templates Management** to open the **Templates Management** page. + - Templates Management supports creating two types of templates: commands and Playbooks. Users can quickly create automated tasks in Quick Commands and Jobs Management, improving work efficiency. +![v4_mode_manage_1](../../../../img/v4_mode_manage_1.png) + +## 1 Create Template + +!!! tip "Using Playbook-type template as an example, demonstrating the workflow for creating users on target assets." + - Enter the Job Center page and select Templates Management feature + - Switch to the `Playbook Management` tab + - Click the `Create` button to create or upload a Playbook template + - Set template visibility `Scope` (controls whether other users can see this template); default is `Private`, meaning only the creator can see it + - Fill in template name and description information +![v4_mode_manage_2](../../../../img/v4_mode_manage_2.png) + +!!! tip "" + - After completing basic information for the Playbook template, click Confirm to create the template. After successful creation, click the Playbook template name to enter the template detailed configuration page. +![v4_mode_manage_3](../../../../img/v4_mode_manage_3.png) + +!!! tip "" + - Click the `Workspace` tab to create a main.yml file, as shown below: +![v4_mode_manage_4](../../../../img/v4_mode_manage_4.png) + +!!! tip "" + - After editing is complete, click the `Save` button at the top of the page to save the main.yml file. + +## 2 Template Execution + +!!! tip "" + - On the Jobs Management page, click the `Execute` button to view and monitor task execution progress. +![v4_mode_manage_5](../../../../img/v4_mode_manage_5.png) diff --git a/docs/manual/admin/workbench/my_assets/assets_connect.en.md b/docs/manual/admin/workbench/my_assets/assets_connect.en.md new file mode 100644 index 000000000..2779aa7b3 --- /dev/null +++ b/docs/manual/admin/workbench/my_assets/assets_connect.en.md @@ -0,0 +1,19 @@ +# Connected Assets + +!!! tip "" + - Click the **Workbench** button on the navigation bar to open the **Workbench** page. + - Click **My Assets > Connected Assets** to open the **Connected Assets** page. + - The Connected Assets page mainly displays asset information that administrators have authorized to the current user. The left side of the page shows the asset tree of authorized assets, and the right side shows all assets authorized to the current user. +![v4_assets_connect_1](../../../../img/v4_assets_connection_1.png) + +!!! tip "" + - Click on an asset name to customize asset names within your permissions. +![v4_assets_connect_2](../../../../img/v4_assets_connection_2.png) + +!!! tip "" + - Click the first button next to an asset name to quickly jump to the Web Terminal page and connect to the corresponding asset. +![v4_assets_connect_3](../../../../img/v4_assets_connection_3.png) + +!!! tip "" + - Click the **Favorite** button to add the current asset to favorites, making it more convenient to quickly search and connect to the asset from the Web Terminal. +![v4_assets_connect_4](../../../../img/v4_assets_connection_4.png) diff --git a/docs/manual/admin/workbench/my_assets/file_explorer.en.md b/docs/manual/admin/workbench/my_assets/file_explorer.en.md new file mode 100644 index 000000000..9d1f55787 --- /dev/null +++ b/docs/manual/admin/workbench/my_assets/file_explorer.en.md @@ -0,0 +1,26 @@ +# File Explorer + +!!! tip "" + - Click the **Workbench** button on the navigation bar to open the **Workbench** page. + - Click **My Assets > File Explorer** to open the **File Explorer** page. + - By default, SFTP directory for upload and download is set to `/tmp`. SFTP directory is bound to asset platforms. The default SFTP directory in JumpServer cannot be modified; if modification is needed, create a new system platform in **Settings > Platform List** and adjust accordingly. + - Click the **Settings** icon to modify the default SFTP path. +![v4_file_manage_1](../../../../img/v4_file_manage_1.png) + +!!! tip "" + - The file explorer page is shown below; right-click on the upper black area to select text labels to display their meanings: +![v4_file_manage_2](../../../../img/v4_file_manage_2.png) + +!!! tip "" + - Click the corresponding information in the left node tree to enter the SFTP directory in the asset. When an asset has only one account authorized, clicking on the asset name directly enters the SFTP directory of the authorized user for that asset. + - When an asset has multiple accounts authorized, click on the asset name and then select the corresponding account to enter the corresponding SFTP directory. +![v4_file_manage_3](../../../../img/v4_file_manage_3.png) + +!!! tip "After entering the SFTP directory, you can perform operations on folders or files. Two operation methods are supported:" + - **Method 1:** Right-click directly on the right side of the page to bring up the operation menu. + - **Method 2:** Use buttons in the upper section to perform corresponding operations. +![v4_file_manage_4](../../../../img/v4_file_manage_4.png) + +!!! tip "" + - JumpServer supports adjusting the view for displaying files. The adjustment button and adjusted view are shown below: +![v4_file_manage_5](../../../../img/v4_file_manage_5.png) diff --git a/docs/manual/admin/workbench/my_assets/file_transfer.en.md b/docs/manual/admin/workbench/my_assets/file_transfer.en.md new file mode 100644 index 000000000..30d5dd6ce --- /dev/null +++ b/docs/manual/admin/workbench/my_assets/file_transfer.en.md @@ -0,0 +1,11 @@ +# File Transfer + +## 1 Batch Transfer + +!!! warning "Currently only supports file transfer for Linux assets. For security reasons, the default transfer directory is `/tmp` and cannot be modified. For specifying a directory, use the **File Explorer** feature." + +!!! tip "" + - Click the **Workbench** button on the navigation bar to open the **Workbench** page. + - Click **My Assets > File Transfer** to open the **File Transfer** page. + - JumpServer supports batch file transfer functionality, allowing you to upload local files to multiple managed Linux assets. +![v4_file_transfer_1](../../../../img/v4_file_transfer_1.png) diff --git a/docs/manual/admin/workbench/my_assets/web_terminal.en.md b/docs/manual/admin/workbench/my_assets/web_terminal.en.md new file mode 100644 index 000000000..153f76b4c --- /dev/null +++ b/docs/manual/admin/workbench/my_assets/web_terminal.en.md @@ -0,0 +1,166 @@ +# Web Terminal + +!!! tip "" + - The Web Terminal page is primarily used for asset connections. Click the **Web Terminal** button on the **Workbench** page or the icon in the top-right corner to access the Web Terminal page and initiate asset connections from this page. +![v4_web_terminal_1](../../../../img/v4_web_terminal_1.png) + + +## 1 Organization Switch + +!!! tip "" + - JumpServer supports displaying authorized assets for users by organization on the Web Terminal page. When a user has asset authorization across multiple organizations, you can switch organizations using the buttons shown in the figure and obtain authorized assets from that organization; when needing to connect to assets, you can select desired assets from the left asset tree, or search by asset name or IP for quick target finding, then click to login. +![av4_web_terminal_2](../../../../img/v4_web_terminal_2.png) + + +## 2 Batch Asset Connection + +!!! tip "" + - The Web Terminal page supports users to batch connect to assets. Use the batch selection options in the top-left corner to select assets to connect, then perform batch connection operations on these assets. +![v4_web_terminal_3](../../../../img/v4_web_terminal_3.png) + + +## 3 Session Dragging + +!!! tip "" + - When users connect to assets using **Web Terminal** mode, the corresponding Tab windows can be manually dragged to adjust their display positions. +![v4_web_terminal_4](../../../../img/v4_web_terminal_4.png) + + +## 4 Session Switching + +!!! tip "" + - When users connect to multiple assets, they can use the **ALT+Left/Right** keyboard shortcut to quickly switch between sessions. + +## 5 Session Split Screen + +!!! tip "" + - When users connect to assets, they can open multiple sessions in one browser interface and view real-time execution results of batch commands, making it convenient to compare session content. (Currently supports up to 4 split screens per session). +![v4_web_terminal_5](../../../../img/v4_web_terminal_5.png) + + +## 6 Asset Connection + +!!! tip "" + - The main function of the Web Terminal page is asset connection. Different asset types support different connection methods. + +### 6.1 Linux Asset Connection + +!!! tip "Web CLI" + - Web CLI is command-line connection mode. Connection result is shown below: + ![v4_web_terminal_6](../../../../img/v4_web_terminal_6.png) + +!!! tip "Web SFTP" + - Web SFTP connection result is shown below: + ![v4_web_terminal_8](../../../../img/v4_web_terminal_8.png) + +!!! tip "SSH Client" + - JumpServer supports connecting to Linux assets by launching **SSH Client**. Users select **Client - SSH Client** mode to connect, which will launch JumpServer client, and JumpServer client will launch **local SecureCRT client or other clients and auto-fill connection data**, enabling connection. + ![v4_web_terminal_10](../../../../img/v4_web_terminal_10.png) + +!!! tip "SSH Wizard" + - JumpServer supports connecting to Linux assets by **generating encrypted information**. Users select **Client - SSH Wizard** mode to connect, which will generate encrypted connection information. Users can copy the encrypted information here and execute it in any command line to connect to the corresponding asset. + ![v4_web_terminal_12](../../../../img/v4_web_terminal_12.png) + + +### 6.2 Windows Asset Connection + +!!! tip "" + - Windows assets display the number of currently connected users in the connection button for that asset. +![v4_web_terminal_14](../../../../img/v4_web_terminal_14.png) + + +!!! tip "" + - JumpServer supports three connection modes for Windows assets: **Web GUI**, **Remote Desktop Client**, and **RDP File**. + +!!! tip "Web GUI" + - Web GUI mode connects to Windows directly on the JumpServer page, as shown below: + ![v4_web_terminal_15](../../../../img/v4_web_terminal_15.png) + +!!! tip "Remote Desktop" + - **Remote Desktop** mode will launch JumpServer client, which launches Windows local Mstsc program to connect to Windows asset. Mac system users need to download official Microsoft RDP client (accessible through the **Download** button in the **Help** module of **Web Terminal**). + ![v4_web_terminal_17](../../../../img/v4_web_terminal_17.png) + +!!! tip "RDP File" + - **RDP File** mode downloads an RDP file. Clicking the RDP file launches Windows local Mstsc program to connect to Windows asset. Mac system users need to download official Microsoft RDP client (accessible through the **Download** button in the **Help** module of **Web Terminal**). + ![v4_web_terminal_19](../../../../img/v4_web_terminal_19.png) + ![v4_web_terminal_20](../../../../img/v4_web_terminal_20.png) + +### 6.3 Database Asset Connection + +!!! tip "" + - JumpServer provides multiple ways to login to databases. For example, command-line Web CLI, graphical Web GUI, database proxy direct connection DB Client, and remote application mode launching DBeaver. + +!!! tip "" + Database connection methods support: + +| Database Type | Web GUI | Web CLI | Database Client (X-Pack) | DB Connection Wizard (X-Pack) | Remote Application Mode | +| --- | --- | --- | --- | --- | --- | +| MySQL | ✓ | ✓ | ✓ | ✓ | ✓ | +| MariaDB | ✓ | ✓ | ✓ | ✓ | ✓ | +| PostgreSQL | ✓ | ✓ | ✓ | ✓ | ✓ | +| Oracle (X-Pack) | ✓ | ✓ | ✓ | ✓ | ✓ | +| SQLServer (X-Pack) | ✓ | ✓ | ✓ | ✓ | ✓ | +| Redis | ✗ | ✓ | ✓ | ✓ | ✓ | +| MongoDB | ✗ | ✓ | ✓ | ✓ | ✓ | +| ClickHouse (X-Pack) | ✗ | ✓ | ✗ | ✗ | ✓ | +| Dameng (X-Pack) | ✓ | ✗ | ✗ | ✗ | ✓ | + +!!! info "Description" + - ✓: Supports this connection mode + - ✗: Does not support this connection mode + +!!! tip "Web CLI Mode" + - On the Web Terminal page, click a database and select **Web CLI** mode to connect to the database. Connection result is shown below: +![v4_web_terminal_21](../../../../img/v4_web_terminal_21.png) + + +!!! tip "Web GUI Mode" + - On the Web Terminal page, click a database and select **Web GUI** mode for graphical database connection. + + +!!! tip "Client Mode" + - **Database Client:** This feature requires pre-configuration of JumpServer client. On the Web Terminal page, click a database, select **Client** mode, **Database Client** to connect to database. This will launch DBeaver client on your personal PC (if pre-configured). Download JumpServer client by clicking the **Download** button in the **Help** module of **Web Terminal**. + - **DB Connection Wizard:** On the Web Terminal page, click a database, select **Client** mode, **DB Connection Wizard** to generate database connection information (information generated by **Client** mode provides two connection methods to database). + + +!!! tip "Remote Application Mode" + - On the Web Terminal page, click a database and select **Remote Application** mode to connect to database. Prerequisite for using this mode is that administrators have pre-set remote applications and published remote applications like Navicat or DBeaver. For detailed explanation of remote applications, refer to the [Remote Applications](../../system_settings/remote_apps.md) section. + + +## 7 File Explorer + +!!! tip "" + - On the Web Terminal page, click the **File Explorer** button and select the **Connect** button to enter the file explorer module. For detailed explanation of file explorer, refer to the [File Explorer](file_explorer.md) section. + +## 8 View + +!!! tip "" + - The **View** button is used to display the asset connection interface in full screen (only available when connecting to assets). +![v4_web_terminal_22](../../../../img/v4_web_terminal_22.png) + +## 9 Language + +!!! tip "" + - JumpServer supports multiple languages including English, Chinese, Japanese, Portuguese, Spanish, and Russian. Use the **Language** button to switch the display language of JumpServer system. +![v4_web_terminal_23](../../../../img/v4_web_terminal_23.png) + +## 10 Settings + +!!! tip "" + - The **Settings** button is used to configure related settings during JumpServer asset connection process, including basic configuration, graphical interface, and command-line modules. + +!!! tip "Basic Configuration" + - **Async Load Asset Tree**: Set whether to load asset tree in real-time during asset connection. + +!!! tip "Graphical Configuration" + - **RDP Resolution**: Set RDP connection resolution; default is Auto. + - **RDP Smart Size**: When enabled, automatically calculates optimal zoom ratio between local and remote windows. + - **Keyboard Layout**: Select keyboard layout to use when connecting to Windows assets. + - **RDP Client Options**: Configure whether to enable full screen mode and disk mounting when RDP client connects. + - **Remote Application Connection Mode**: Select connection mode for remote applications (Web or **Client** mode). + +!!! tip "Command-line Configuration" + - **Character Terminal Font Size**: Set display size of terminal font. + - **Character Terminal Backspace As Ctrl+H**: Set whether to enable Ctrl+H as delete key shortcut. + - **Right-click Quick Paste**: Set whether to enable right-click quick paste functionality in command-line. +![v4_web_terminal_24](../../../../img/v4_web_terminal_24.png) diff --git a/docs/manual/admin/workbench/other/system_tool.en.md b/docs/manual/admin/workbench/other/system_tool.en.md new file mode 100644 index 000000000..1cb2d0dab --- /dev/null +++ b/docs/manual/admin/workbench/other/system_tool.en.md @@ -0,0 +1,9 @@ +# System Tools + +!!! warning "Requires system administrator to enable at `System Settings > Feature Settings > System Tools`." + +!!! tip "" + - Click the **Workbench** button on the navigation bar to open the **Workbench** page. + - Click **Other > System Tools** to open the **System Tools** page. + - Click the **System Tools** tab on the left side of the page to access the system tools page. This page includes system tools such as Ping, Telnet, Nmap, Tcpdump, and Traceroute to check network connections between assets and JumpServer service. +![v4_system_tool_1](../../../../img/v4_system_tool_1.png) diff --git a/docs/manual/client/asset_connection.en.md b/docs/manual/client/asset_connection.en.md new file mode 100644 index 000000000..4f3c5c360 --- /dev/null +++ b/docs/manual/client/asset_connection.en.md @@ -0,0 +1,57 @@ +# Asset Connection + +!!! info "Note: RDP client connection and database client connection are JumpServer enterprise features." + +## Linux Asset Connection + +!!! tip "" + - The client supports SSH, SFTP, and VNC protocols to connect to target Linux assets. After connection, you can execute commands and upload/download files. + +!!! tip "" + - In the Linux asset list, click **Connect** next to the target asset name to open the connection window. + - In the connection window, select the protocol, choose the account to use, and click the **Confirm** button to connect to the asset. + +![image](../../img/clientV4_03.png) + +## Windows Asset Connection + +!!! tip "" + - The client supports RDP, VNC, SSH, and SFTP protocols to connect to target Windows assets. After connection, you can execute commands and upload/download files. + +!!! tip "" + - In the Windows asset list, click **Connect** next to the target asset name to open the connection window. + - In the connection window, select the protocol, choose the account to use, and click the **Confirm** button to connect to the asset. + +## Database Asset Connection + +### Local Client Configuration + +!!! tip "" + - Before using the client method to connect to databases, you need to configure the local client invocation path. + - Click the settings button in the top-right corner to enter the settings page. + - Click **Database** to expand the list of supported databases; here MySQL is used as an example. + - After selecting **MySQL**, a list of available applications appears on the right with download options. Click **Download Application** and install it. + - After installation, click **Select path** to configure its installation path, then you can use the application to connect to databases. + +![image](../../img/clientV4_04.png) + +### Connect to Asset + +!!! tip "" + - In the **Database** asset list, click **Connect** next to the target asset name to automatically invoke the client to connect to the asset. + +## Device Asset Connection + +!!! tip "" + - The client supports SSH protocol to connect to target device assets. Device assets include **General**, **Cisco**, **Huawei**, and **H3C** by default. + +!!! tip "" + - In the **Devices** asset list, click **Connect** next to the target asset name to open the connection window. + - In the connection window, select the protocol, choose the account to use, and click the **Confirm** button to connect to the asset. + +## Favorite Asset Connection + +!!! tip "" + - On the connection page for various asset types, you can right-click on the target asset and click **Favorite** to add the target asset to the favorites list. + +![image](../../img/clientV4_05.png) diff --git a/docs/manual/client/client_installation.en.md b/docs/manual/client/client_installation.en.md new file mode 100644 index 000000000..0bb31feff --- /dev/null +++ b/docs/manual/client/client_installation.en.md @@ -0,0 +1,26 @@ +# Client Download and Installation + +## Introduction + +!!! tip "" + JumpServer Client is a cross-platform desktop application that supports Windows, macOS, and Linux systems. Users can use the client to locally connect and manage remote assets (Windows, Linux, databases, and network devices) managed by JumpServer. + +!!! warning "Note: The new client (>=v4.0.0) only supports JumpServer versions **v4.10.13 and above**. Please ensure your server version meets the requirements." + + +## Client Download + +Installation packages for various platforms + +| Operating System | Architecture | Download Link | +| --- | --- | --- | +| Windows | x64 | [JumpServerClient_{{ jumpserver.client_tag }}_x64-setup.exe](https://github.com/jumpserver/client/releases/download/v{{ jumpserver.client_tag }}/JumpServerClient_{{ jumpserver.client_tag }}_x64-setup.exe) | +| macOS | Apple Silicon (M1/M2) | [JumpServerClient_{{ jumpserver.client_tag }}_aarch64.dmg](https://github.com/jumpserver/client/releases/download/v{{ jumpserver.client_tag }}/JumpServerClient_{{ jumpserver.client_tag }}_aarch64.dmg) | +| macOS | Intel (x64) | [JumpServerClient_{{ jumpserver.client_tag }}_x64.dmg](https://github.com/jumpserver/client/releases/download/v{{ jumpserver.client_tag }}/JumpServerClient_{{ jumpserver.client_tag }}_x64.dmg) | +| Linux | amd64 (Ubuntu/Debian) | [JumpServerClient_{{ jumpserver.client_tag }}_amd64.deb](https://github.com/jumpserver/client/releases/download/v{{ jumpserver.client_tag }}/JumpServerClient_{{ jumpserver.client_tag }}_amd64.deb) | + +> Users can visit '/core/download/' page to download the client installation package for the corresponding platform. Enterprise server supports downloading in intranet environments. + +## Client Interface Preview + +![Client Login Interface](../../img/clientV4_01.png) diff --git a/docs/manual/client/connection_settings.en.md b/docs/manual/client/connection_settings.en.md new file mode 100644 index 000000000..a9461ebf7 --- /dev/null +++ b/docs/manual/client/connection_settings.en.md @@ -0,0 +1,65 @@ +# Connection Settings + +!!! tip "" + - Click the settings button in the top-right corner of the client to open the connection settings page. + +## General + +!!! tip "" + - This page allows you to adjust the client's **language**, **character set**, **character terminal settings**, and **resolution**. + +![image](../../img/clientV4_10.png) + +## Appearance + +!!! tip "" + - This page allows you to adjust the client's **appearance color**, **primary color**, and **font**. + +![image](../../img/clientV4_11.png) + +## Application Configuration + +### Command-line Terminal + +**SSH** + +!!! tip "" + - This page allows you to adjust local application configuration for connecting to assets through SSH protocol. + +![image](../../img/clientV4_06.png) + +**Telnet** + +!!! tip "" + - This page allows you to adjust local application configuration for testing port connections through Telnet protocol; the specific page is similar to SSH. + +### File Transfer + +**SFTP** + +!!! tip "" + - This page allows you to adjust local application configuration for transferring files through SFTP protocol. + +![image](../../img/clientV4_07.png) + +### Remote Desktop + +**RDP** + +!!! tip "" + - This page allows you to adjust local application configuration for connecting to assets through RDP protocol. + - Windows users default to local MSTSC application. Mac users default to Microsoft Remote Desktop application, and need to define RDP file opening method in the system. Linux users need to install and configure Remmina or XFreeRDP. + +![image](../../img/clientV4_08.png) + +**VNC** + +!!! tip "" + - This page allows you to adjust local application configuration for connecting to assets through VNC protocol; the specific page is similar to RDP. + +### Database + +!!! tip "" + - This page allows you to adjust local application configuration for connecting to database assets, supporting MySQL, MariaDB, MongoDB, Redis, PostgreSQL, Oracle, SQL Server databases. + +![image](../../img/clientV4_09.png) diff --git a/docs/manual/disclaimer.en.md b/docs/manual/disclaimer.en.md new file mode 100644 index 000000000..33a702828 --- /dev/null +++ b/docs/manual/disclaimer.en.md @@ -0,0 +1,9 @@ +# Disclaimer + +This document is provided "as is". FIT2CLOUD, Inc. makes no warranties related to this document, including but not limited to implied warranties of merchantability and fitness for a particular purpose. This document may contain technical or other errors or typographical errors. FIT2CLOUD, Inc. reserves the right to revise the information in this document at any time without notice. This document and the software described in it are confidential information of FIT2CLOUD, Inc. and its licensors, provided under the license of FIT2CLOUD, Inc. + +FIT2CLOUD, Inc., FIT2CLOUD logo are trademarks of FIT2CLOUD, Inc. and/or its affiliates, registered with China's National Patent and Trademark Office and other countries/regions. All other trademarks and registered trademarks are assets of their respective owners. + +**Trademark:** + +**FIT2CLOUD®** diff --git a/docs/manual/env.en.md b/docs/manual/env.en.md new file mode 100644 index 000000000..123deec3a --- /dev/null +++ b/docs/manual/env.en.md @@ -0,0 +1,94 @@ +# Parameter Description + +!!! warning "Attention" + - Close JumpServer service before modifying configuration files. + +## 1 Core Parameter Description +!!! tip "" + - Open the config.txt configuration file. + + ```sh + vi /opt/jumpserver/config/config.txt + ``` + +!!! tip "" + - Core parameters are as follows: + +| Parameter Name | Default Value | Optional | Description | +| :--- | :--- | :--- | :--- | +| SECRET_KEY | '' | - | Key for encrypting/decrypting sensitive fields | +| BOOTSTRAP_TOKEN | '' | - | Token used for component registration with Core service | +| DEBUG | false | true
    false | Debug mode; shows more information when page requests API errors if enabled | +| DEBUG_DEV | false | true
    false | Debug development mode; backend logs show more information if enabled | +| LOG_LEVEL | DEBUG | DEBUG
    INFO
    WARNING
    ERROR
    CRITICAL | Log level | +| LOG_DIR | /data/jumpserver/core/logs | - | Log directory | +| DB_ENGINE | mysql | - | Database engine | +| DB_NAME | jumpserver | - | Database name | +| DB_HOST | 127.0.0.1 | - | Database address | +| DB_PORT | 3306 | - | Database port | +| DB_USER | root | - | Database user | +| DB_PASSWORD | '' | - | Database user password | +| DB_USE_SSL | false | true
    false | Enable SSL for database | +| REDIS_HOST | 127.0.0.1 | - | Redis address | +| REDIS_PORT | 6379 | - | Redis port | +| REDIS_PASSWORD | '' | - | Redis password | +| REDIS_USE_SSL | false | true
    false | Enable SSL for Redis | +| REDIS_SSL_KEY | null | - | Redis SSL Key | +| REDIS_SSL_CERT | null | - | Redis SSL certificate | +| REDIS_SSL_CA | null | - | Redis SSL CA certificate | +| REDIS_SSL_REQUIRED | null | - | Whether Redis SSL certificate is required | +| REDIS_MAX_CONNECTIONS | 100 | - | Maximum Redis connections | +| REDIS_SENTINEL_HOSTS | '' | - | Redis Sentinel addresses (multiple addresses separated by /) | +| REDIS_SENTINEL_PASSWORD | '' | - | Redis Sentinel password | +| REDIS_SENTINEL_SOCKET_TIMEOUT | null | - | Redis Sentinel Socket timeout | +| REDIS_DB_CELERY | 3 | 0-15 | Redis database number for Celery tasks | +| REDIS_DB_CACHE | 4 | 0-15 | Redis database number for cache | +| REDIS_DB_SESSION | 5 | 0-15 | Redis database number for user sessions | +| REDIS_DB_WS | 6 | - | Redis database number for WebSocket | +| TOKEN_EXPIRATION | 3600 * 24 (s) | - | Expiration time for API-created user tokens
    # If configured as empty or 0, default is 3600 | +| DEFAULT_EXPIRED_YEARS | 70 (year) | - | Default expiration years for created resources, e.g. authorization rules
    # Not allowed to modify | +| SESSION_COOKIE_DOMAIN | null | - | User session cookie domain, e.g. fit2cloud.com | +| CSRF_COOKIE_DOMAIN | null | - | User CSRF cookie domain; defaults to same as SESSION_COOKIE_DOMAIN | +| SESSION_COOKIE_NAME_PREFIX | null | - | User-set session cookie name prefix | +| SESSION_COOKIE_AGE | 3600 * 24 (s) | - | User session cookie expiration time | +| SESSION_EXPIRE_AT_BROWSER_CLOSE | false | true
    false | User session expires after browser closes | +| CONNECTION_TOKEN_ONETIME_EXPIRATION | 5 * 60 | >= 5 * 60 | ConnectionToken can only be used once within validity period | +| CONNECTION_TOKEN_REUSABLE_EXPIRATION | 3600 * 24 * 30 (s) | - | ConnectionToken can be reused multiple times within validity period | +| CONNECTION_TOKEN_REUSABLE | false | true
    false | Whether ConnectionToken can be reused multiple times | +| AUTH_CUSTOM | false | true
    false | Enable custom user authentication | +| AUTH_CUSTOM_FILE_MD5 | '' | - | MD5 value of custom user authentication file | +| MFA_CUSTOM | false | true
    false | Enable custom MFA authentication | +| MFA_CUSTOM_FILE_MD5 | '' | - | MD5 value of custom MFA authentication file | +| AUTH_TEMP_TOKEN | false | true
    false | Enable temporary password feature | +| AUTH_SSO | false | true
    false | Enable SSO authentication | +| AUTH_SSO_AUTHKEY_TTL | 60 * 15 (s) | SSO authentication key TTL | +| LOGIN_REDIRECT_TO_BACKEND | '' | Direct (direct to internal login page)
    OpenID
    CAS
    SAML2
    OAuth2 service provider name (System Settings) | After enabling third-party authentication, directly redirect to authentication service without countdown page, e.g. OpenID | +| LOGIN_REDIRECT_MSG_ENABLED | true | true
    false | Enable third-party redirect countdown page | +| SYSLOG_ADDR | '' | - | SysLog service address | +| SYSLOG_FACILITY | user | - | SysLog FACILITY | +| SYSLOG_SOCKTYPE | 2 | - | SysLog SockType | +| PERM_EXPIRED_CHECK_PERIODIC | 60 * 60 (s) | - | Period for checking expired asset authorization rules and expiring user authorization trees | +| LANGUAGE_CODE | en | zh
    en
    ja | Language | +| TIME_ZONE | Asia/Shanghai | - | Time zone | +| SESSION_COOKIE_SECURE | false | true
    false | User session cookie security mode; only allows HTTPS when enabled | +| DOMAINS | '' | - | Specify allowed domains for JumpServer application | +| CSRF_COOKIE_SECURE | false | true
    false | User CSRF token security mode; only allows HTTPS when enabled | +| REFERER_CHECK_ENABLED | false | true
    false | Whether to enable REFERER validation | +| CSRF_TRUSTED_ORIGINS | - | - | CSRF same-origin trust; multiple addresses separated by `,` | +| SESSION_ENGINE | cache | - | User session engine | +| SESSION_SAVE_EVERY_REQUEST | true | true
    false | Save user session on every request | +| SESSION_EXPIRE_AT_BROWSER_CLOSE_FORCE | false | true
    false | Force session expiration after browser closes | +| SERVER_REPLAY_STORAGE | {} | - | Server-side recording storage
    e.g.:
    {
    'TYPE': 's3',
    'BUCKET': '',
    'ACCESS_KEY': '',
    'SECRET_KEY': '',
    'ENDPOINT': ''
    }
    # Components upload recordings to Core service, Core automatically uploads to configured object storage | +| CHANGE_AUTH_PLAN_SECURE_MODE_ENABLED | true | true
    false | Change password plan secure mode
    When enabled, users cannot change their own password;
    When disabled, users can change their own password;
    e.g. root changing root | +| SECURITY_VIEW_AUTH_NEED_MFA | true | true
    false | Require MFA verification | +| SECURITY_DATA_CRYPTO_ALGO | null | - | Data encryption algorithm | +| GMSSL_ENABLED | false | true
    false | Enable national encryption algorithm (data encryption algorithm)
    SECURITY_DATA_CRYPTO_ALGO
    GMSSL_ENABLED
    # If both configured, SECURITY_DATA_CRYPTO_ALGO takes priority | +| OPERATE_LOG_ELASTICSEARCH_CONFIG | {} | - | Storage ES configuration for "changed fields" in operation logs
    e.g.:
    {
    "INDEX": "",
    "HOSTS": "",
    "OTHER": "",
    "IGNORE_VERIFY_CERTS": "",
    "INDEX_BY_DATE": "",
    "DOC_TYPE": ""
    } | +| MAGNUS_ORACLE_PORTS | 30000-30030 | - | Oracle port range that Magnus component needs to listen to | +| APPLET_DOWNLOAD_HOST | '' | - | Download address for Applet and other software | +| FTP_FILE_MAX_STORE | 0 | - | FTP file upload/download backup threshold (unit: M); when value ≤ 0, files are not backed up | +| MAX_LIMIT_PER_PAGE | 10000 | - | Set maximum number of allowed export records | +| FILE_UPLOAD_SIZE_LIMIT_MB | 200 | - | Set maximum file upload size limit (unit: MB) | +| THROTTLE_RATES_ANON | 60/min | string | Rate limit for unauthenticated users | +| THROTTLE_RATES_USER | 180/min | string | Rate limit for users | +| THROTTLE_RATES_SERVICE_ACCOUNT | 300/min | string | Rate limit for component accounts | diff --git a/docs/manual/prologue_admin.en.md b/docs/manual/prologue_admin.en.md new file mode 100644 index 000000000..41e703fee --- /dev/null +++ b/docs/manual/prologue_admin.en.md @@ -0,0 +1,61 @@ +# Preface + +## Overview + +Thank you for choosing JumpServer bastion host. This manual describes in detail the usage methods of JumpServer bastion host (hereinafter referred to as "JumpServer" or "system"), including JumpServer quick start, personal information, system settings, console, audit, workbench, work orders, and other modules. + +The content provided in this manual is for general guidance only and does not guarantee coverage of all use cases for all product models. Due to version upgrades, device models, different project configuration files, and other reasons, the content provided in the manual may not be consistent with the actual interface of the device you are using. Please use the actual device interface information as the standard. This manual will not explain differences caused by the aforementioned situations. + +For the purpose of feature introduction and configuration examples, the manual may use IP addresses, URLs, domain names, etc. Unless otherwise specified, the above content is for illustration purposes only and does not represent any actual meaning. + +## Intended Audience + +This document is primarily applicable to users of JumpServer, including system administrators, network administrators, and others. This document assumes readers have some understanding of the following areas: + +- Basic network communication protocols such as TCP/IP, HTTP. + +- Basic working principles, configuration, and operation of common devices (systems) such as databases, servers, routers, switches. + +- Basic working principles and operation of bastion hosts and network security operation and maintenance tools. + +## Getting Help + +If you encounter any problems while using JumpServer, please contact support personnel in the enterprise WeChat group, online support personnel in the QQ group, or login to the Fit2Cloud support portal at https://support.fit2cloud.com/ to submit a ticket, or call 400-052-0755 for assistance. + +Company regional contact addresses: + +- Hangzhou: Room 1502, Building A, Huaxing Times, 478 Wensan Road, Xihu District, Hangzhou, Zhejiang Province. + +- Beijing: Room 501, 715, Building A, Caifu Center Office Building, 7 East Third Ring Middle Road, Chaoyang District, Beijing. + +- Shanghai: Room 12E, Zhaofu Global Building, 1800 Zhongshan West Road, Xuhui District, Shanghai. + +- Shenzhen: Room 1005, Building 4, Zhuoyue Century Center, 2030 Jinjiang Road, Futian District, Shenzhen, Guangdong Province. + +- Guangzhou: Unit 2410A, Poly Kloway Zhongying, 9 Huaqiang Road, Tianhe District, Guangzhou, Guangdong Province. + +- Nanjing: Room 906A, Xuanyi Plaza Office Building, 66 Hexi Avenue, Jianye District, Nanjing, Jiangsu Province. + +- Chengdu: Room 2505, Block C, Xikedun International Plaza, 666 Tianfu Avenue Middle Segment, High-tech Zone, Chengdu, Sichuan Province. + +- Wuhan: Room 902, Guanggu Times Plaza, Building A, 101 Guanshan Avenue, Hongshan District, Wuhan, Hubei Province. + +- Suzhou: Rooms 1908, 1909, Zhongrun Center, 399 Baodai East Road, Wuzhong District, Suzhou, Jiangsu Province. + +- Xi'an: Room 2908, Gaoxin International, 33 Keji Road, Yanta District, Xi'an, Shaanxi Province. + +- Jinan: Room 1203, 12th Floor, Block D, Zhonghuo Plaza, 6-17 Liberation East Road, Lixia District, Jinan, Shandong Province. + +- Qingdao: Room 1111, Building 6, Fushan Houye Center, 567 Liaoyang West Road, Shifu District, Qingdao, Shandong Province. + +- Zhengzhou: Room 1320, Shenglongcheng Second District Center, Block A, 567 Hanghai Middle Road, Erqi District, Zhengzhou, Henan Province. + +- Changsha: Room 1608, 16th Floor, Building A, Lugu Information Harbor, Yuelu District, Changsha, Hunan Province. + +- Xiamen: Unit 1009, Kangle Financial Building, 9 Yilan Road, Siming District, Xiamen, Fujian Province. + +- Hefei: Room 1716, E Building, Greenland Center, Baohe District, Hefei, Anhui Province. + +- Chongqing: Room 1108B, Building A, Xiexin Center, 99 Wuyi Road, Jiefangbei Street, Yuzhong District, Chongqing. + +- Tianjin: Room 813, 2-1-8 Floor, Ronghui Plaza, Nankai District, Tianjin. diff --git a/docs/manual/prologue_auditor.en.md b/docs/manual/prologue_auditor.en.md new file mode 100644 index 000000000..5efa46a81 --- /dev/null +++ b/docs/manual/prologue_auditor.en.md @@ -0,0 +1,61 @@ +# Preface + +## Overview + +Thank you for choosing JumpServer bastion host. This manual describes in detail the usage methods of JumpServer bastion host (hereinafter referred to as "JumpServer" or "system"), including session audit and log audit information. + +The content provided in this manual is for general guidance only and does not guarantee coverage of all use cases for all product models. Due to version upgrades, device models, different configuration files, and other reasons, the content provided in the manual may not be consistent with the actual interface of the device you are using. Please use the actual device interface information as the standard. This manual will not explain differences caused by the aforementioned situations. + +For the purpose of feature introduction and configuration examples, the manual may use IP addresses, URLs, domain names, etc. Unless otherwise specified, the above content is for illustration purposes only and does not represent any actual meaning. + + +## Intended Audience + +This document is primarily applicable to users performing JumpServer system audits. This document assumes readers have some understanding of the following areas: + +- Basic working principles and operation of bastion hosts. +- Basic concepts of computer networks and information security. +- Basic knowledge of common operating systems and network protocols (such as SSH, RDP, VNC, etc.). + + +## Getting Help + +If you encounter any problems while using JumpServer, please contact support personnel in the enterprise WeChat group, online support personnel in the QQ group, or login to the Fit2Cloud support portal at https://support.fit2cloud.com/ to submit a ticket, or call 400-052-0755 for assistance. + +Company regional contact addresses: + +- Hangzhou: Room 1502, Building A, Huaxing Times, 478 Wensan Road, Xihu District, Hangzhou, Zhejiang Province. + +- Beijing: Room 501, 715, Building A, Caifu Center Office Building, 7 East Third Ring Middle Road, Chaoyang District, Beijing. + +- Shanghai: Room 12E, Zhaofu Global Building, 1800 Zhongshan West Road, Xuhui District, Shanghai. + +- Shenzhen: Room 1005, Building 4, Zhuoyue Century Center, 2030 Jinjiang Road, Futian District, Shenzhen, Guangdong Province. + +- Guangzhou: Unit 2410A, Poly Kloway Zhongying, 9 Huaqiang Road, Tianhe District, Guangzhou, Guangdong Province. + +- Nanjing: Room 906A, Xuanyi Plaza Office Building, 66 Hexi Avenue, Jianye District, Nanjing, Jiangsu Province. + +- Chengdu: Room 2505, Block C, Xikedun International Plaza, 666 Tianfu Avenue Middle Segment, High-tech Zone, Chengdu, Sichuan Province. + +- Wuhan: Room 902, Guanggu Times Plaza, Building A, 101 Guanshan Avenue, Hongshan District, Wuhan, Hubei Province. + +- Suzhou: Rooms 1908, 1909, Zhongrun Center, 399 Baodai East Road, Wuzhong District, Suzhou, Jiangsu Province. + +- Xi'an: Room 2908, Gaoxin International, 33 Keji Road, Yanta District, Xi'an, Shaanxi Province. + +- Jinan: Room 1203, 12th Floor, Block D, Zhonghuo Plaza, 6-17 Liberation East Road, Lixia District, Jinan, Shandong Province. + +- Qingdao: Room 1111, Building 6, Fushan Houye Center, 567 Liaoyang West Road, Shifu District, Qingdao, Shandong Province. + +- Zhengzhou: Room 1320, Shenglongcheng Second District Center, Block A, 567 Hanghai Middle Road, Erqi District, Zhengzhou, Henan Province. + +- Changsha: Room 1608, 16th Floor, Building A, Lugu Information Harbor, Yuelu District, Changsha, Hunan Province. + +- Xiamen: Unit 1009, Kangle Financial Building, 9 Yilan Road, Siming District, Xiamen, Fujian Province. + +- Hefei: Room 1716, E Building, Greenland Center, Baohe District, Hefei, Anhui Province. + +- Chongqing: Room 1108B, Building A, Xiexin Center, 99 Wuyi Road, Jiefangbei Street, Yuzhong District, Chongqing. + +- Tianjin: Room 813, 2-1-8 Floor, Ronghui Plaza, Nankai District, Tianjin. diff --git a/docs/manual/prologue_user.en.md b/docs/manual/prologue_user.en.md new file mode 100644 index 000000000..dfb67049a --- /dev/null +++ b/docs/manual/prologue_user.en.md @@ -0,0 +1,58 @@ +# Preface + +## Overview + +Thank you for choosing JumpServer bastion host. This manual describes in detail the usage methods of JumpServer bastion host (hereinafter referred to as "JumpServer" or "system"), including JumpServer quick start, personal information, system settings, console, audit, workbench, work orders, and other modules. + +The content provided in this manual is for general guidance only and does not guarantee coverage of all use cases for all product models. Due to version upgrades, device models, different project configuration files, and other reasons, the content provided in the manual may not be consistent with the actual interface of the device you are using. Please use the actual device interface information as the standard. This manual will not explain differences caused by the aforementioned situations. + +For the purpose of feature introduction and configuration examples, the manual may use IP addresses, URLs, domain names, etc. Unless otherwise specified, the above content is for illustration purposes only and does not represent any actual meaning. + +## Intended Audience + +This document is primarily applicable to users of JumpServer, including regular users, developers, and others. This document assumes readers have some understanding of the following areas: + +- Basic working principles and operation of bastion hosts and network security operation and maintenance tools. + + +## Getting Help + +If you encounter any problems while using JumpServer, please contact support personnel in the enterprise WeChat group, online support personnel in the QQ group, or login to the Fit2Cloud support portal at https://support.fit2cloud.com/ to submit a ticket, or call 400-052-0755 for assistance. + +Company regional contact addresses: + +- Hangzhou: Room 1502, Building A, Huaxing Times, 478 Wensan Road, Xihu District, Hangzhou, Zhejiang Province. + +- Beijing: Room 501, 715, Building A, Caifu Center Office Building, 7 East Third Ring Middle Road, Chaoyang District, Beijing. + +- Shanghai: Room 12E, Zhaofu Global Building, 1800 Zhongshan West Road, Xuhui District, Shanghai. + +- Shenzhen: Room 1005, Building 4, Zhuoyue Century Center, 2030 Jinjiang Road, Futian District, Shenzhen, Guangdong Province. + +- Guangzhou: Unit 2410A, Poly Kloway Zhongying, 9 Huaqiang Road, Tianhe District, Guangzhou, Guangdong Province. + +- Nanjing: Room 906A, Xuanyi Plaza Office Building, 66 Hexi Avenue, Jianye District, Nanjing, Jiangsu Province. + +- Chengdu: Room 2505, Block C, Xikedun International Plaza, 666 Tianfu Avenue Middle Segment, High-tech Zone, Chengdu, Sichuan Province. + +- Wuhan: Room 902, Guanggu Times Plaza, Building A, 101 Guanshan Avenue, Hongshan District, Wuhan, Hubei Province. + +- Suzhou: Rooms 1908, 1909, Zhongrun Center, 399 Baodai East Road, Wuzhong District, Suzhou, Jiangsu Province. + +- Xi'an: Room 2908, Gaoxin International, 33 Keji Road, Yanta District, Xi'an, Shaanxi Province. + +- Jinan: Room 1203, 12th Floor, Block D, Zhonghuo Plaza, 6-17 Liberation East Road, Lixia District, Jinan, Shandong Province. + +- Qingdao: Room 1111, Building 6, Fushan Houye Center, 567 Liaoyang West Road, Shifu District, Qingdao, Shandong Province. + +- Zhengzhou: Room 1320, Shenglongcheng Second District Center, Block A, 567 Hanghai Middle Road, Erqi District, Zhengzhou, Henan Province. + +- Changsha: Room 1608, 16th Floor, Building A, Lugu Information Harbor, Yuelu District, Changsha, Hunan Province. + +- Xiamen: Unit 1009, Kangle Financial Building, 9 Yilan Road, Siming District, Xiamen, Fujian Province. + +- Hefei: Room 1716, E Building, Greenland Center, Baohe District, Hefei, Anhui Province. + +- Chongqing: Room 1108B, Building A, Xiexin Center, 99 Wuyi Road, Jiefangbei Street, Yuzhong District, Chongqing. + +- Tianjin: Room 813, 2-1-8 Floor, Ronghui Plaza, Nankai District, Tianjin. diff --git a/docs/manual/user/profile.en.md b/docs/manual/user/profile.en.md new file mode 100644 index 000000000..780ba6be8 --- /dev/null +++ b/docs/manual/user/profile.en.md @@ -0,0 +1,126 @@ +# Personal Profile + +!!! tip "" + - Click the **Username** button in the top right corner of the page to enter the **Personal Profile** interface. This page mainly displays personal account information and allows you to configure personal authentication and other settings. + +![image](../../img/profile01.png) +## 1 Personal Information +!!! tip "" + - This page displays basic information for regular users. On this page, you can also perform authentication configurations, such as MFA authentication, passwords, SSH key login information, etc. If the administrator has configured enterprise WeChat, DingTalk authentication, etc., you can also bind the corresponding account authentication information on this page. Additionally, this page allows you to set message subscriptions, which by default include in-site messages and email settings. If the administrator has configured enterprise WeChat, DingTalk, etc., you can also enable related message subscriptions here. +![image](../../img/profile02.png) + +## 2 MFA Authentication + +!!! tip "" + - MFA (Multi-Factor Authentication) refers to adding an additional layer of security verification beyond username and password authentication, such as SMS verification codes, email verification codes, dynamic tokens, etc. JumpServer supports multiple MFA authentication methods. Users can click **MFA Authentication** on the **Authentication Configuration** panel on the right side of the personal profile page to configure it. + +**OTP Dynamic Token** +!!! tip "" + - OTP (One-Time Password) is a dynamic password where a new password is required for each authentication, generated by a dynamic token device. +![image](../../img/profile_mfa01.png) + +- After clicking to enter the configuration page, download the relevant application according to the instructions and bind it as prompted. + +![image](../../img/profile_mfa02.png) + +![image](../../img/profile_mfa03.png) + +- After successful configuration, when users complete login with username and password, they need to enter the dynamic token for two-factor verification. + + +**Face Recognition** + +!!! tip "" + - Face recognition is a biometric authentication method that verifies user identity through facial features. + +**1 Configure MFA Face Recognition** +**Record facial information on the user details page and enable MFA** + +![image.png](../../img/Facelive1.png) + +- Log out and attempt to log in again, select face verification +![image.png](../../img/Facelive2.png) + +- Complete face verification within 30 seconds +![image.png](../../img/Facelive3.png) + + + +**Email Verification** + +!!! tip "" + - You can use email verification codes as two-factor verification. Users can complete login by entering the email verification code during login. + - Enable email functionality in the personal information section +![image.png](../../img/profile_mfa05.png) + - Go to **System Settings > Notification Settings** to enable email verification and configure the email server information. +![image.png](../../img/profile_mfa04.png) + - Select **Email** in the MFA authentication methods after login and enter the corresponding verification code to complete login. +![image.png](../../img/profile_mfa06.png) + +**SMS Authentication** + +!!! tip "" + - You can use SMS verification codes as two-factor verification. Users can complete login by entering the SMS verification code during login. + - Bind your phone number in the personal information section to enable SMS verification +![image.png](../../img/profile_mfa07.png) + - Select **SMS** in the MFA authentication methods after login and enter the corresponding verification code to complete login. +![image.png](../../img/profile_mfa08.png) + + +## 3 Authentication Settings +!!! tip "" + - Regular users can perform authentication configuration and message subscription configuration for their own accounts on the personal profile page. You can view and set user authentication information, including passwords and SSH key login information. + - Login Password Settings: Regular users can update their current account password on this page. + - SSH Public Key Settings: Regular users can set SSH public keys and download them on this page, which are used when logging in to the bastion host using SSH terminal. +![image](../../img/profile03.png) + +## 4 Access Keys +!!! tip "" + - Access keys are a way for users to access the bastion host through the API. Users can view and generate access keys on this page. + - Generate Access Key: Users can click the **Generate Access Key** button to generate one. After generation, please save it properly. After the access key is generated, it cannot be viewed again, so please keep it safely. + - This API key permissions are consistent with the current user role permissions. + - For API documentation, refer to: https:///api/docs/. +![image](../../img/profile04.png) + +## 5 Connection Token +!!! tip "" + - Connection tokens are a type of authentication information that combines authentication with asset connection, supporting one-click login to assets. Currently supported components include: KoKo, Lion, Magnus, Razor, etc. Users can view connection token information and expire tokens. The creation methods for connection tokens are as follows: + - Connect to SSH protocol assets: Connect to Linux assets through the web terminal and select the connection method as **Client** to create token information. + - Connect to RDP protocol assets: Connect to RDP assets through the web terminal and select the connection method as **Client** to create token information. + - Connect to database applications: Connect to database applications through the web terminal and select the connection method as **Database Client** to create token information. + - Create by calling the API method. + +![image](../../img/profile05.png) + +## 6 Preferences +!!! tip "" + - Users can configure the web terminal service on the **Preferences** page. + + +### 6.1 **Basic** +!!! tip "" + - Click the **Basic** button on the left side of the personal settings page to set encryption passwords for files exported from the JumpServer page. +![image](../../img/profile06.png) + +### 6.2 **Web Terminal** + +!!! tip "" + - Click the **Web Terminal** button in the middle of the personal settings page to configure parameters when connecting to assets on the web terminal page. +![image](../../img/profile07.png) + +Detailed configuration explanation: + +| Configuration Item | Description | +| --- | --- | +| Asynchronous Asset Tree Loading | Whether to load the asset tree in real-time during asset connection. | +| Default Connection Method | Default **Current Window** | +| RDP Resolution | Change RDP resolution. Default **Auto**. | +| Keyboard Layout | Select the keyboard layout to use when connecting to Windows assets. | +| RDP Client Options | Whether to enable fullscreen, multi-monitor display, and disk mounting for RDP client connections. | +| RDP Color Quality | Select the color depth for remote sessions. | +| RDP Smart Sizing | Whether the client computer should scale the content on the remote computer to fit the client window size when adjusting window size. | +| Remote Application Connection Method | Select the connection method for remote applications, web or client method. | +| File Name Conflict Resolution | When uploading files through the KOKO component, if the uploaded file conflicts with files in the original directory, select whether to replace the original file or add a suffix to the newly uploaded file. | +| Character Terminal Font Size | Set the display size of terminal font. | +| Character Terminal Backspace AS Ctrl+H | Whether to enable the Ctrl+H shortcut key as the delete key in the command line. | +| Right-Click Quick Paste | Whether to enable right-click quick paste in the command line. | diff --git a/docs/manual/user/ticket.en.md b/docs/manual/user/ticket.en.md new file mode 100644 index 000000000..2b0e4d83f --- /dev/null +++ b/docs/manual/user/ticket.en.md @@ -0,0 +1,50 @@ +# Work Order + +!!! tip "" + - The work order feature is mainly responsible for requesting and reviewing authorization work orders, as well as managing command filtering and asset login reviews. JumpServer authorization requests support a two-level approval workflow. After users submit a work order request and the corresponding approvers in the configured workflow approve it, the user can obtain permissions for the requested assets or user login request reviews and command filtering. + +## 1 My Requests + +!!! tip "" + - The My Requests page mainly displays detailed records of work orders created by users. On this page, you can request work orders. + +**Request Work Order** + +![image](../../../img/workorder01.png) +![image](../../../img/workorder02.png) + +Parameter Description + +| Parameter | Description | +|--------------------|--------------------------------------------------------------------| +| Title | The title of the work order. | +| Organization | The organization for which the work order is requesting permissions and where the JumpServer user belongs. | +| Node | The node where the asset is located. Selecting a node means requesting permissions for all assets under that entire node. | +| Asset | The specific asset that the user is requesting. | +| Request Account | The login account for the asset that the user is requesting. | +| Operation | The action permissions that the user is requesting. | +| Start Date, Expiration Date | The validity period for the user's requested permissions. | + +**View Work Order** + +!!! tip "" + - Click the **Work Order Title** button to enter the work order details page. The work order details page includes the work order's basic information, request information, and approvers. On this page, you can also communicate with approvers. +![image](../../../img/workorder03.png) + +**Cancel Work Order** + +!!! tip "" + - You can manually cancel the work order on the work order details page. +![image](../../../img/workorder04.png) + +## 2 Awaiting My Approval + +!!! tip "" + - On the Awaiting My Approval page, click the **Work Order Name** button to review and approve the work order. When approvers view the work order, they can modify the permissions for assets, accounts, operations, etc. requested by the applicant. + +![image](../../../img/workorder05.png) +![image](../../../img/workorder06.png) + +- In addition to approving on the JumpServer page, JumpServer also supports direct work order approval through enterprise WeChat and DingTalk. When the approver's enterprise WeChat or DingTalk is bound, the approver can approve applicant work orders in real-time through enterprise WeChat or DingTalk. + +![image](../../../img/workorder07.png) diff --git a/docs/quick_start.en.md b/docs/quick_start.en.md new file mode 100644 index 000000000..b569af473 --- /dev/null +++ b/docs/quick_start.en.md @@ -0,0 +1,154 @@ +# Quick Start +## 1 Install JumpServer +!!! tip "" + - Supports mainstream Linux distributions (based on Debian / RedHat, including domestic operating systems) + - Refer to [Linux standalone installation and deployment guide](installation/setup_linux_standalone/offline_install.md) for quick JumpServer deployment + +!!! info "After successful installation, access and log in to JumpServer via browser" + ```sh + Address: http://: + Username: admin + Password: ChangeMe + ``` + +## 2 Asset Management +### 2.1 Preparation +!!! tip "" + - Prepare two test assets and one database to verify functionality. + +!!! tip "" + + | IP Address | Hostname | Port | Operating System | Admin User | Password | + | ---------- | -------- | ---- | ---------------- | ---------- | -------- | + | 172.16.80.11 | test_ssh01 | 22 | Centos 7 | root | Test2020.L | + | 172.16.80.21 | test_rdp01 | 3389 | Windows 10 | administrator | Test2020.W | + | 172.16.80.31 | test_mysql01 | 3306 | MySQL 5 | root | Test2020.M | + +!!! warning "Note" + - Windows assets need [Windows SSH setup](guide/asset_requirements/windows_ssh.md) before executing automation tasks such as `update asset information` and `connectivity testing`; this is not required for logging in to Windows assets. + - MySQL application requires granting `Core` and `KoKo` remote access permissions [MySQL requirements](guide/asset_requirements/mysql.md) + +### 2.2 Edit Asset Tree +!!! tip "" + - Click `Asset Management` - `Asset List` on the left side of the page. Right-click on the root node `Default` to create three nodes: `SSH Server`, `RDP Server`, and `Database`. +!!! tip "" + - Asset tree example: + + ``` + Default + ├─ SSH Server + └─ RDP Server + └─ DB Server + ``` + +!!! warning "Note" + - The root node `Default` cannot be renamed. Right-click on nodes to `add`, `delete`, and `rename` nodes, and perform asset-related operations. + +### 2.3 Create Assets +!!! tip "" + - Click `Asset Management` - `Asset List` - `Hosts` - `Create` to create a Linux server, and during asset creation, create a privileged user with the `admin user` and `password` from the table above. + - The creation process for Windows assets is the same. + +!!! tip "" + - Example of creating a Linux asset: + +!!! tip "" + + | Name | IP/Hostname | Asset Platform | Node | Protocol Group | Account List | + | ---- | ----------- | --------------- | ---- | -------------- | ------------ | + | test_ssh01 | 172.16.80.11 | Linux | /Default/SSH Server | ssh 22 | Add | + +!!! tip "" + - Example of adding login asset user: + +!!! tip "" + + | Name | Username | Privileged User | Cipher Type | Password | + | ---- | -------- | --------------- | ----------- | -------- | + | 172.16.80.11_root | root | Yes | Password | Test2020.L | + +!!! warning "Note" + - `Name` must be unique. Either `password` or `key` is required; some assets may not allow password authentication and can use key authentication instead. + - `Privileged user` only supports `SSH` protocol, used for asset `connectivity testing`, `user push`, `batch password change` and other automation tasks. + - If assets cannot connect normally, verify the privileged user's `username` and `password` are correct and the `privileged user` can SSH from `JumpServer` host to the asset host. + +### 2.4 Create Database Application +!!! tip "" + - Click `Asset Management` - `Asset List` - `Create` - `Database` and select `MySQL Database`. + +!!! tip "" + - Example of creating a MySQL database application: + +!!! tip "" + + | Name | IP/Hostname | Node | Username | Database | Account List | + | ---- | ----------- | ---- | -------- | -------- | ------------ | + | test_mysql01 | 172.16.80.31 | /Default/DB Server | test | mysql:3306 | Add | + +!!! tip "" + - Example of adding database login user: + +!!! tip "" + + | Name | Username | Password | Cipher Type | Password | + | ---- | -------- | -------- | ----------- | -------- | + | 172.16.80.23_root | root | root | Password | Test2020.M | + +!!! warning "Note" + - Name, hostname, and database are required fields. + +## 3 Create Authorization Rules +!!! tip "" + - Click `Permission Management` - `Asset Authorization` - `Create` to create an authorization. + - The authorization process for Windows assets and MySQL databases is the same as below. + +!!! tip "" + - Example of creating a login authorization rule (e.g., Linux asset): + +!!! tip "" + + | Name | User | User Group | Asset | Node | Account | Action | + | ---- | ---- | ---------- | ----- | ---- | ------- | ------ | + | admin_ssh01 | Administrator(admin) | - | test_ssh01(172.16.80.11) | - | All accounts | ✓ All | + +!!! warning "Note" + - `Name`: The authorization name, must be unique. + - `User (Group)` and `Asset (Node)` have a one-to-one relationship, so when you have different asset types like `Linux` and `Windows`, you should create separate `authorization rules` for each. + +## 4 User Login +!!! tip "" + - Click `Web Terminal` in the top-right corner to connect to assets. + +!!! warning "Note" + - Users can only see assets they have been authorized by administrators. If no assets appear after login, please contact your administrator. + +## 5 System Settings +!!! tip "" + - Click `System Settings` in the top-right corner to configure. + +### 5.1 Basic Settings +!!! tip "" + + | Item | Default | Description | + | ---- | ------- | ----------- | + | Forgotten password URL | | Customize if using external authentication systems like LDAP, OpenID | + +### 5.2 Email Settings +!!! tip "" + - We support integrating email configuration through `SMTP` or `EXCHANGE`. + +=== "SMTP" + !!! tip "" + + +## 6 Common Feature Operations +!!! tip "" + - **[Upload and download via SFTP][Upload and download via SFTP]** + - **[Manage Redis databases][Manage Redis databases]** + + +[Upload and download via SFTP]: https://kb.fit2cloud.com/?p=115 +[Windows Upload and Download]: https://kb.fit2cloud.com/?p=87 +[Restrict IP Login]: https://kb.fit2cloud.com/?p=199 +[Manage Redis databases]: https://kb.fit2cloud.com/?p=91 +[Manage Database Applications]: https://kb.fit2cloud.com/?p=79 diff --git a/docs/teaching_video.en.md b/docs/teaching_video.en.md new file mode 100644 index 000000000..cb7b89deb --- /dev/null +++ b/docs/teaching_video.en.md @@ -0,0 +1,19 @@ +# Teaching Videos + +## 1 Installation and Deployment + +[![Installation and Deployment](img/video/install.png){ width="280"}](https://www.bilibili.com/video/BV1vR4y1w7sG/?spm_id_from=333.788&vd_source=202cc7e93ceb73b966c426555ab06c3f) + +## 2 Asset Management +[![User Management](img/video/user_manage.png){ width="280"}](https://www.bilibili.com/video/BV1Nt4y1s7qe/?spm_id_from=333.788&vd_source=202cc7e93ceb73b966c426555ab06c3f) +[![Asset Management](img/video/asset_manage.png){ width="280"}](https://www.bilibili.com/video/BV1L5411X7XV/?spm_id_from=333.788&vd_source=202cc7e93ceb73b966c426555ab06c3f) +[![Domain Gateway](img/video/domain_gw.png){ width="280"}](https://www.bilibili.com/video/BV1954y1Z7wo/?spm_id_from=333.788&vd_source=202cc7e93ceb73b966c426555ab06c3f)
    +[![Command Filtering](img/video/cmd_acls.png){ width="280"}](https://www.bilibili.com/video/BV1k54y1d7xs/?spm_id_from=333.788&vd_source=202cc7e93ceb73b966c426555ab06c3f) +[![Application Management](img/video/application_manage.png){ width="280"}](https://www.bilibili.com/video/BV19g411d7Mx/?spm_id_from=333.788&vd_source=202cc7e93ceb73b966c426555ab06c3f) + +## 3 Log Audit +[![Log Audit](img/video/log_audit.png){ width="280"}](https://www.bilibili.com/video/BV1ua411E7PP/?spm_id_from=333.788&vd_source=202cc7e93ceb73b966c426555ab06c3f) + +## 4 Other Configuration +[![Email Service](img/video/emaill_config.png){ width="280"}](https://www.bilibili.com/video/BV18R4y1w7pG/?spm_id_from=333.788&vd_source=202cc7e93ceb73b966c426555ab06c3f) +[![LDAP Authentication](img/video/ldap_config.png){ width="280"}](https://www.bilibili.com/video/BV13T4y1q7g3/?spm_id_from=333.788&vd_source=202cc7e93ceb73b966c426555ab06c3f) diff --git a/docs/user_stories.en.md b/docs/user_stories.en.md new file mode 100644 index 000000000..0a64f55f5 --- /dev/null +++ b/docs/user_stories.en.md @@ -0,0 +1,17 @@ +# User Cases + +!!! tip "" + JumpServer is a widely popular open source bastion machine that has been refined through testing and extensively serves industries such as banking, securities, manufacturing, logistics, media, and the internet, with over 200,000 cumulative installations. + +!!! tip "" + - [JumpServer bastion machine escorts SF Technology's ultra-large-scale asset security operations](https://blog.fit2cloud.com/?p=1147){:target="_blank"} + - [JumpServer bastion machine makes "Big Wisdom" hybrid IT operations management smarter](https://blog.fit2cloud.com/?p=882){:target="_blank"} + - [JumpServer bastion machine helps Zhongshanyou enhance security operations capabilities in multi-cloud environments](https://blog.fit2cloud.com/?p=732){:target="_blank"} + - [Ctrip JumpServer bastion machine deployment and operations best practices](https://blog.fit2cloud.com/?p=851){:target="_blank"} + - [Tencent Overseas Game builds game security operations capability based on JumpServer](https://blog.fit2cloud.com/?p=3704){:target="_blank"} + - [Wanhua Chemical manages globally distributed IT assets through JumpServer and achieves linkage with cloud management platform](https://blog.fit2cloud.com/?p=3504){:target="_blank"} + - [Snowflake Beer JumpServer bastion machine usage experience](https://blog.fit2cloud.com/?p=3412){:target="_blank"} + - [Little Red Book JumpServer bastion machine large-scale asset cross-version migration journey](https://blog.fit2cloud.com/?p=516){:target="_blank"} + - [ZTO Express JumpServer host security operations best practices](https://blog.fit2cloud.com/?p=708){:target="_blank"} + - [Oriental Pearl JumpServer efficient management and control of heterogeneous and distributed cloud assets](https://blog.fit2cloud.com/?p=687){:target="_blank"} + - [Jiangsu Rural Credit Union JumpServer bastion machine helps industry cloud security operations](https://blog.fit2cloud.com/?p=666){:target="_blank"} diff --git a/mkdocs.yml b/mkdocs.yml index ccce2508c..fd7b12817 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -302,6 +302,7 @@ plugins: build: true site_name: JumpServer Documentation nav_translations: + 参数说明: Configuration Parameters 产品介绍: Product Introduction 快速入门: Quick Start 安装部署: Installation