Skip to content

Commit

Permalink
docs update (#75)
Browse files Browse the repository at this point in the history 
* repo-sync-2024-07-16T16:42:12+0800

* format docs

* format docs
  • Loading branch information
@zheyang0825
zheyang0825 committed Jul 16, 2024
1 parent c24e0a8 commit c1fffa7
Show file tree
Hide file tree
Showing 2 changed files with 107 additions and 42 deletions.
2 changes: 1 addition & 1 deletion .circleci/config.yml
View file
Original file line number Diff line number Diff line change
Expand Up @@ -227,4 +227,4 @@ workflows:
- pypi_publish:
matrix:
parameters:
python_ver: ["3.10"]
python_ver: ["3.10"]
147 changes: 106 additions & 41 deletions docs/quick_start/step1.ipynb
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,27 +18,34 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## 选项一：仿真模式部署CapsuleManager\n",
"## Capsule Manager 部署"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### 选项一：仿真模式部署CapsuleManager\n",
"\n",
"如果你希望使用仿真模式进行体验，则可以按下列说明进行。\n",
"\n",
"### 1. 运行CapsuleManager镜像\n",
"#### 1. 运行CapsuleManager镜像\n",
"\n",
"```bash\n",
"docker run -it --name capsule-manager-sim --network=host secretflow/capsule-manager-sim-ubuntu22.04:latest bash\n",
"```\n",
"\n",
"### 2. 启动CapsuleManager\n",
"#### 2. 启动CapsuleManager\n",
"\n",
"CapsuleManager 默认会启用mTLS，关于如何配置mTLS可以参考[CapsuleManager mTLS](https://github.com/secretflow/capsule-manager/blob/master/README.md#mutual-tls)：\n",
"```bash\n",
"./capsule_manager --server-cert-key-path <SERVER_CERT_KEY_PATH> \\\n",
" --server-cert-path <SERVER_CERT_PATH> \\\n",
" --client-ca-cert-path <CLIENT_CA_CERT_PATH>\n",
"./capsule_manager --tls_config.server_private_key_path <SERVER_CERT_KEY_PATH> \\\n",
" --tls_config.server_cert_path <SERVER_CERT_PATH> \\\n",
" --tls_config.client_ca_cert_path <CLIENT_CA_CERT_PATH>\n",
"```\n",
"如果不希望开启mTLS，可以添加启动参数`--enable-tls false` 来**关闭mTLS功能**（注意关闭mTLS是不安全的，生产环境建议启动mTLS）：\n",
"如果不希望开启mTLS，可以添加启动参数`--tls_config.enable_tls false` 来**关闭mTLS功能**（注意关闭mTLS是不安全的，生产环境建议启动mTLS）：\n",
"```bash\n",
"./capsule_manager --enable-tls false\n",
"./capsule_manager --tls_config.enable_tls false\n",
"```\n",
"默认的监听端口为8888，您可以在启动时添加`--port xx`参数修改为其他端口号。"
]
Expand All @@ -47,7 +54,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## 选项二：在SGX机器上运行CapsuleManager"
"### 选项二：在SGX机器上运行CapsuleManager"
]
},
{
Expand All @@ -61,13 +68,13 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"### 1. 检查sgx环境\n",
"#### 1. 检查sgx环境\n",
"**宿主机**上执行以下命令确保存在/dev/sgx_enclave和/dev/sgx_provision。\n",
"```bash\n",
"ls /dev | grep sgx\n",
"```\n",
"\n",
"### 2. 运行镜像\n",
"#### 2. 运行镜像\n",
"\n",
"```bash\n",
"docker run -it --name capsule-manager-sgx --network=host -v /dev/sgx_enclave:/dev/sgx/enclave -v /dev/sgx_provision:/dev/sgx/provision --privileged=true secretflow/capsule-manager-sgx-ubuntu22.04:latest bash\n",
Expand All @@ -78,7 +85,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"### 3. 修改 PCCS 配置\n",
"#### 3. 修改 PCCS 配置\n",
"\n",
"> 提示：如果您还没有PCCS服务，则可以参考[部署PCCS](../architecture/tee/sgx.md#如何部署pccs服务)。\n",
"\n",
Expand Down Expand Up @@ -106,7 +113,7 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"### 4. 生成私钥后，使用私钥进行build。\n",
"#### 4. 生成私钥后，使用私钥进行build。\n",
"\n",
"您首先需要生成私钥，然后使用以下命令构建occlum。生成私钥可以参考下列脚本，生成的私钥保存在当前目录的private_key.pem。请妥善保存您的私钥，不要泄露给其他人。\n",
"\n",
Expand All @@ -125,30 +132,30 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"### 5. 运行服务\n",
"#### 5. 运行服务\n",
"\n",
"CapsuleManager 默认会启用mTLS，关于如何配置mTLS可以参考[CapsuleManager mTLS](https://github.com/secretflow/capsule-manager/blob/master/README.md#mutual-tls)\n",
"\n",
"\n",
"> 默认的监听端口为8888，您可以在启动时添加`--port xx`参数修改为其他端口号\n",
"\n",
"```bash\n",
"occlum run /bin/capsule_manager --server-cert-key-path <SERVER_CERT_KEY_PATH> \\\n",
" --server-cert-path <SERVER_CERT_PATH> \\\n",
" --client-ca-cert-path <CLIENT_CA_CERT_PATH>\n",
"occlum run /bin/capsule_manager --tls_config.server_private_key_path <SERVER_CERT_KEY_PATH> \\\n",
" --tls_config.server_cert_path <SERVER_CERT_PATH> \\\n",
" --tls_config.client_ca_cert_path <CLIENT_CA_CERT_PATH>\n",
"```\n",
"\n",
"如果不希望开启mTLS，可以添加启动参数`--enable-tls false` 来**关闭mTLS功能**（注意关闭mTLS是不安全的，生产环境建议启动mTLS）：\n",
"如果不希望开启mTLS，可以添加启动参数`--tls_config.enable_tls false` 来**关闭mTLS功能**（注意关闭mTLS是不安全的，生产环境建议启动mTLS）：\n",
"```bash\n",
"occlum run /bin/capsule_manager --enable-tls false\n",
"occlum run /bin/capsule_manager --tls_config.enable_tls false\n",
"```"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### 7. 获取CapsuleManager的mrenclave\n",
"#### 6. 获取CapsuleManager的mrenclave\n",
"\n",
"执行下列命令可以获得CapsuleManager的mrenclave，mrenclave是表征CapsuleManager代码、数据、运行环境等的度量值，详细解释见[Enclave](../architecture/tee/sgx.md#enclave)。\n",
"\n",
Expand All @@ -163,24 +170,24 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## 选项三：TDX模式部署CapsuleManager\n",
"### 选项三：TDX模式部署CapsuleManager\n",
"\n",
"如果你希望在TDX的TD中进行体验，则可以按下列说明进行。\n",
"\n",
"### 1. 检查环境\n",
"#### 1. 检查环境\n",
"**TD VM**中执行以下命令确保存在/dev/tdx_guest。**请注意，如果您的环境中存在的是/dev/tdx-guest而非/dev/tdx_guest，则说明您的tdx版本较老，需要更新。**\n",
"```bash\n",
"ls /dev | grep tdx\n",
"```\n",
"\n",
"### 2. 运行CapsuleManager镜像\n",
"#### 2. 运行CapsuleManager镜像\n",
"在**TD VM**中运行CapsuleManager镜像。\n",
"\n",
"```bash\n",
"docker run -it --name capsule-manager-tdx --network=host -v /dev/tdx_guest:/dev/tdx_guest --privileged=true secretflow/capsule-manager-tdx-ubuntu22.04:latest bash\n",
"```\n",
"\n",
"### 3. 修改 PCCS 配置\n",
"#### 3. 修改 PCCS 配置\n",
"\n",
"> 提示：如果您还没有PCCS服务，则可以参考[部署PCCS](../architecture/tee/sgx.md#如何部署pccs服务)。\n",
"\n",
Expand All @@ -196,21 +203,21 @@
"\n",
"```\n",
"\n",
"### 4. 启动CapsuleManager\n",
"#### 4. 启动CapsuleManager\n",
"\n",
"CapsuleManager 默认会启用mTLS，关于如何配置mTLS可以参考[CapsuleManager mTLS](https://github.com/secretflow/capsule-manager/blob/master/README.md#mutual-tls)：\n",
"```bash\n",
"./capsule_manager --server-cert-key-path <SERVER_CERT_KEY_PATH> \\\n",
" --server-cert-path <SERVER_CERT_PATH> \\\n",
" --client-ca-cert-path <CLIENT_CA_CERT_PATH>\n",
"./capsule_manager --tls_config.server_private_key_path <SERVER_CERT_KEY_PATH> \\\n",
" --tls_config.server_cert_path <SERVER_CERT_PATH> \\\n",
" --tls_config.client_ca_cert_path <CLIENT_CA_CERT_PATH>\n",
"```\n",
"如果不希望开启mTLS，可以添加启动参数`--enable-tls false` 来**关闭mTLS功能**（注意关闭mTLS是不安全的，生产环境建议启动mTLS）：\n",
"如果不希望开启mTLS，可以添加启动参数`--tls_config.enable_tls false` 来**关闭mTLS功能**（注意关闭mTLS是不安全的，生产环境建议启动mTLS）：\n",
"```bash\n",
"./capsule_manager --enable-tls false\n",
"./capsule_manager --tls_config.enable_tls false\n",
"```\n",
"默认的监听端口为8888，您可以在启动时添加`--port xx`参数修改为其他端口号。\n",
"\n",
"### 5. 获取CapsuleManager所在的VM度量值\n",
"#### 5. 获取CapsuleManager所在的VM度量值\n",
"\n",
"目前暂无简易工具可以获取度量值，您可以在后续步骤中获取远程认证报告并记录其中携带的度量值用于后验。"
]
Expand All @@ -219,11 +226,11 @@
"cell_type": "markdown",
"metadata": {},
"source": [
"## 选项四：CSV模式部署CapsuleManager\n",
"### 选项四：CSV模式部署CapsuleManager\n",
"\n",
"如果你希望在海光CSV虚拟机中进行体验，则可以按下列说明进行。\n",
"\n",
"### 1. 检查环境\n",
"#### 1. 检查环境\n",
"**CSV VM**中执行以下命令确保存在/dev/csv-guest。\n",
"```bash\n",
"ls /dev/ | grep csv\n",
Expand All @@ -247,31 +254,89 @@
"sudo insmod csv-guest.ko\n",
"```\n",
"\n",
"### 2. 运行CapsuleManager镜像\n",
"#### 2. 运行CapsuleManager镜像\n",
"在**CSV VM**中运行CapsuleManager镜像。\n",
"\n",
"```bash\n",
"docker run -it --name capsule-manager-csv --network=host -v /dev/csv-guest:/dev/csv-guest --privileged=true secretflow/capsule-manager-csv-ubuntu22.04:latest bash\n",
"```\n",
"\n",
"### 3. 启动CapsuleManager\n",
"#### 3. 启动CapsuleManager\n",
"\n",
"CapsuleManager 默认会启用mTLS，关于如何配置mTLS可以参考[CapsuleManager mTLS](https://github.com/secretflow/capsule-manager/blob/master/README.md#mutual-tls)：\n",
"```bash\n",
"./capsule_manager --server-cert-key-path <SERVER_CERT_KEY_PATH> \\\n",
" --server-cert-path <SERVER_CERT_PATH> \\\n",
" --client-ca-cert-path <CLIENT_CA_CERT_PATH>\n",
"./capsule_manager --tls_config.server_private_key_path <SERVER_CERT_KEY_PATH> \\\n",
" --tls_config.server_cert_path <SERVER_CERT_PATH> \\\n",
" --tls_config.client_ca_cert_path <CLIENT_CA_CERT_PATH>\n",
"```\n",
"如果不希望开启mTLS，可以添加启动参数`--enable-tls false` 来**关闭mTLS功能**（注意关闭mTLS是不安全的，生产环境建议启动mTLS）：\n",
"如果不希望开启mTLS，可以添加启动参数`--tls_config.enable_tls false` 来**关闭mTLS功能**（注意关闭mTLS是不安全的，生产环境建议启动mTLS）：\n",
"```bash\n",
"./capsule_manager --enable-tls false\n",
"./capsule_manager --tls_config.enable_tls false\n",
"```\n",
"默认的监听端口为8888，您可以在启动时添加`--port xx`参数修改为其他端口号。\n",
"\n",
"### 4. 获取CapsuleManager所在的VM度量值\n",
"#### 4. 获取CapsuleManager所在的VM度量值\n",
"\n",
"目前暂无简易工具可以获取度量值，您可以在后续步骤中获取远程认证报告并记录其中携带的度量值用于后验。"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"## 其他配置"
]
},
{
"cell_type": "markdown",
"metadata": {},
"source": [
"### 持久化配置\n",
"\n",
"CapsuleManager Docker image 在 0.3.3b0 之后的版本中支持持久化存储。在默认配置中，CapsuleManager 仍然是 inmemory 存储，为了支持持久化存储（目前使用 Mysql），可以遵循以下步骤：\n",
"\n",
"#### 1. 创建 Capsule Manager Database\n",
"\n",
"在 Mysql 8.0 数据库使用以下脚本创建数据库\n",
"https://github.com/secretflow/capsule-manager/blob/main/master/capsule-manager/src/storage/sql_storage/cm.sql\n",
"\n",
"#### 2. 配置\n",
"\n",
"需要修改几个配置：\n",
"\n",
"（1）storage_config：替换 db_url 以及 password \n",
"\n",
"（2）enable_inject_cm_key（是否允许注入 cm private key）：\n",
" * false： private key 在启动的时候生成，如果重新启动后，持久化的数据就不可用；\n",
" * true：则需要配置私钥路径 cm_private_key_path 以及对应的证书路径 cm_cert_path。\n",
"\n",
"配置文件参考如下：\n",
"```yaml\n",
"port: 8888 # port\n",
"\n",
"log_config:\n",
" log_dir: /home/admin/dev/logs # log file path\n",
" log_level: info # log level: info/debug/warn/error\n",
" enable_console_logger: true # Whether the log can be printed in the terminal\n",
"\n",
"tls_config:\n",
" enable_tls: false # enable tls\n",
" server_cert_path: \"/host/resources/cert/server.crt\" # path for the Server Certificate\n",
" server_cert_key_path: \"/host/resources/cert/server.key\" # path for the Server Key\n",
" client_ca_cert_path: \"/host/resources/client_ca\" # directory for the Client CA Certificate\n",
"\n",
"storage_config:\n",
" storage_backend: \"mysql\" # storage backend: mysql, inmemory\n",
" db_url: \"mysql://root@localhost:3306/capsulemanager\" # db url\n",
" password: \"********\" # db password\n",
"\n",
"scheme: \"RSA\" # Asymmetric key generation method, SM2/RSA\n",
"\n",
"enable_inject_cm_key: false # enable inject cm key\n",
"cm_private_key_path: script/certs/cm.key # cm private key path\n",
"cm_cert_path: script/certs/cm.crt # cm certificate path\n",
"```"
]
}
],
"metadata": {
Expand Down

0 comments on commit c1fffa7

Please sign in to comment.