# OxOffice Online 設定檔說明

**OxOOL 設定檔位於 /etc/oxool/oxoolwsd.xml**
以下介紹設定檔內容代表之意義與其可設定的值

```XML
<allowed_languages>
預設：de_DE en_GB en_US es_ES fr_FR it nl pt_BR pt_PT ru
說明：設定支援的拼字檢查器、語法檢查器、同義詞庫、連字號的語系，注意，若啟用太多會影響到啟動的效能。
</allowed_languages>

<sys_template_path>
預設：systemplate（系統編譯時已決定的變數）
說明：放置 LibreOfficeKit 呼叫使用的 LibreOffice 動態函式庫所需的執行時期環境，用以做為子行程 chroot jails 環境來源範本。
</sys_template_path>

<child_root_path>
預設：child_root_path（系統編譯時已決定的變數）
說明：用來建立子處理程序 chroot jails 環境的目錄路徑，應與 systemplate 在同一個檔案系統（分割區）上。
</child_root_path>

<mount_jail_tree>
預設：true
說明：控制是否要掛載 systemplate 與 lotemplate，這會比連結或複製每個檔案來的快。
</mount_jail_tree>

<server_name>
預設：空
說明：執行 oxoolwsd 主程式的主機名稱和連接埠號，如果設定為空，那麼會取決於連線需求。但 OxOOL 主機若在反向代理主機後，或是主機名稱無法直接可達的話則必須設定。
</server_name>

<client_port_number>
預設：9980
說明：OxOOL 要監聽的連接埠號。
</client_port_number>

<file_server_root_path>
預設：loleaflet/../
說明：指向檔案伺服器的 root 路徑，應包含 loleaflet 的目錄。
</file_server_root_path>

<hexify_embedded_urls>
預設：false
說明：保護編碼的 URL 不被中間的節點解碼。在 Azure 部署中較有用。
</hexify_embedded_urls>

<convert_to>
預設：false
說明：是否啟用檔案格式轉換。
</convert_to>

<memproportion>
預設：80.0
說明：設定 OxOffice 最大可消耗的系統記憶體百分比，達到後便會開始清理空閒的文件。
</memproportion>

<num_prespawn_children>
預設：1
說明：預設一開機就啟動，用以等待新連線的子處理程序數量。
</num_prespawn_children>

<per_document>
說明：關於文件的設定，包含 OxOffice 的核心設定。

<max_concurrency>
預設：8
說明：處理單一文件時，所使用的最大執行緒數量。
</max_concurrency>

<batch_priority>
預設：5
說明：針對批次處理程序（如 convert-to）降低優先程度，以避免搶走互動式處理程序的資源。
</batch_priority>

<document_signing_url>
預設：無
說明：簽署文件伺服器的端點 URL，若留空則停用簽署文件功能。
</document_signing_url>

<redlining_as_comments>
預設：true
說明：若設定為 true，則會在註解中顯示紅線。
</redlining_as_comments>

<idle_timeout_secs>
預設：3600
說明：設定閒置多久後連線中斷，單位為秒，預設為1小時。
</idle_timeout_secs>

<idlesave_duration_secs>
預設：1800
說明：設定若文件每經修改並閒置幾秒後就自動儲存一次檔案，預設為30秒，設定為0或負值即為停用 。
</idlesave_duration_secs>

<autosave_duration_secs>
預設：1800
說明：設定若文件每經修改後，經幾秒後就自動儲存一次檔案，預設為300秒 ，設定為0或負值即為停用。
</autosave_duration_secs>

<always_save_on_exit>
預設：false
說明：設定不管文件有沒有修改過，一旦關閉文件的編輯畫面就會強制儲存，預設為 false 。
</always_save_on_exit>

<limit_virt_mem_kb>
預設：0
說明：設定每個處理文件的行程可使用的最大虛擬記憶體，0 為未限制，至少要有 1700kb。
</limit_virt_mem_kb>

<limit_stack_mem_kb>
預設：8000
說明：設定每個處理文件的行程可使用的最大stack大小，0 為未限制。
</limit_stack_mem_kb>

<limit_file_size_mb>
預設：0
說明：設定每個處理文件的行程可開啟的最大檔案大小，0 為未限制。
</limit_file_size_mb>

<limit_num_open_files>
預設：0
說明：設定每個處理文件的行程可開啟的最多檔案數量，0 為未限制。
</limit_num_open_files>

<limit_load_secs>
預設：100
說明：設定開啟每個檔案的最大等待秒數，0 為未限制。
</limit_load_secs>

<limit_convert_secs>
預設：100
說明：設定轉換每個檔案的最大等待秒數，0 為未限制。
</limit_convert_secs>

<cleanup>
預設：false
說明：檢查異常消耗資源的文件並砍除對應的 LibreOfficeKit 處理程序，由以下的幾個選項決定其閾值。
<cleanup_interval_ms>
預設：10000
說明：兩次檢查間的間隔（單位為毫秒）。
</cleanup_interval_ms>
<bad_behavior_period_secs>
預設：60
說明：文件被認定是消耗資源並被砍除對應 LibreOfficeKit 處理程序的最小時間間隔。若此間隔內被認定為異常消耗資源的文件不符合條件則會重設間隔（單位為秒）。
</bad_behavior_period_secs>
<idle_time_secs>
預設：300
說明：文件被認定是異常消耗資源狀態候選的最小閒置時間（單位為秒）。
</idle_time_secs>
<limit_dirty_mem_mb>
預設：3072
說明：文件被認定是異常消耗資源狀態候選的最小記憶體使用量（單位為 MB）。
</limit_dirty_mem_mb>
<limit_cpu_per>
預設：85
說明：文件被認定是異常消耗資源狀態候選的最小 CPU 使用量（單位為百分比）。
</limit_cpu_per>
</cleanup>

</per_document>

<per_view>
說明：與開啟文件瀏覽文件相關的設定。
<out_of_focus_timeout_secs>
預設：60
說明：設定當在瀏覽器分頁在失去焦點後，最多在幾秒後就停止更新文件及調暗視窗。
</out_of_focus_timeout_secs>

<idle_timeout_secs>
預設：900
說明：設定當在使用者完全沒有動作時（即便目前焦點在該瀏覽器分頁上），最多在幾秒後就停止更新文件及調暗視窗。
</idle_timeout_secs>
</per_view>

<loleaflet_html>
預設：loleaflet.html
說明：OxOffice Online 的主網頁檔案名稱，請注意，變更完這個設定後，同時也要將以下目錄的網頁名稱變更為與設定檔一致：/usr/share/oxool/loleaflet/dist。
</loleaflet_html>

<logging>
說明：關於記錄檔的設定參數。
<color>
預設：true
說明：是否啟用記錄檔的顏色機制。
</color>

<level>
預設：warning
說明：記錄檔的level設定值，可以設定0-8個等級，或是可以設定為：none（關閉記錄），fatal，critical，error，warning，notice，information，debug，trace。
</level>

<protocol>
預設：false
說明：啟動時就開始記錄最小化的客戶端 JavaScript 協定紀錄（編譯時決定是否啟用）。
</protocol>

<lokit_sal_log>
預設：-INFO-WARN
說明：微調來自 LibreOfficeKit 的紀錄檔訊息。預設會停用來自 LibreOfficeKit 的紀錄檔訊息。
</lokit_sal_log>

<file>
說明：關於記錄檔的相關參數設定。
<property name=“path“>
預設：/var/log/oxoolwsd.log
說明：OxOffice Online 的記錄檔路徑。
<property name=“rotation“>
預設：daily
說明：設定檔案 rotation 機制的策略，可參考 Poco 的 FileChannel 機制。
<property name=“archive“>
預設：timestamp
說明：設定要在封存的紀錄檔名稱上附加時間戳 (timestamp) 或編號 (number)。
<property name=“times“>
預設：local
說明：指定要將紀錄檔 rotation 的時間視為本機時間 (local) 或 UTC 時間。有效的值為 local 與 utc。
<property name=“compress“>
預設：true
說明：設定是否要啟動紀錄檔壓縮功能。
<property name=“purgeAge“>
預設：30 days
說明：紀錄檔最多保存天數，可參考 Poco 的 FileChannel 機制。
<property name=“purgeCount“>
預設：100
說明：紀錄檔最大的保存數，設為 none 以停用清除紀錄檔的功能，可參考 Poco 的 FileChannel 機制。
<property name=“rotateOnOpen“>
預設：true
說明：設定是否在開啟時啟動紀錄檔 rotation 的機制。
<property name=“flush“>
預設：false
說明：設定是否要在記錄每行 log 時啟用 flush 機制，啟用時可能會影響效能，若設定不啟用時，來自不同處理程序的 log 可能不會依照時間順序記錄。
</file>
<anonymize>
<anonymize_user_data>
預設：false
說明：設定是否啟用對紀錄檔中的使用者資料進行匿名／模糊處理，預設為 false。
</anonymize_user_data>

<anonymization_salt>
預設：82589933
說明：設定對紀錄檔中的使用者資料進行匿名／模糊處理時要使用的 salt。使用 64 位元隨機數。
</anonymization_salt>
</anonymize>

</logging>

<loleaflet_logging>
預設：false
說明：設定是否將紀錄檔同時寫入瀏覽器的主控台。
</loleaflet_logging>

<trace_event>
預設：false
說明：控制是否開啟 Chrome Trace Event 檔案的產生流程。
<path>
預設：空
說明：輸出檔案的路徑設定。
</path>
</trace_event>

<trace>
預設：false
說明：將指令與通知紀錄下來。
<path>
預設：空
說明：輸出檔案的路徑設定。
</path>

<filter>
<message>
預設：空
說明：設定排除特定記錄以節省空間的正規表示式規則。
</message>
</filter>

<outgoing>
<record>
預設：false
說明：設定是否要記錄輸出的訊息。
</record>
</outgoing>
</trace>

<net>
說明：網路相關設定。
<proto>
預設：all
說明：設定開放使用 IPv4 或是 IPv6 或是全部的網路協定。
</proto>

<listen>
預設：any
說明：設定主程式可綁定的位置，可設為 any 或 loopback。
</listen>

<service_root>
預設：無
說明：設定所有頁面、websocket 等路徑的前綴字串。
</service_root>

<proxy_prefix>
預設：false
說明：設定是否啟用傳遞給重新導向請求的 ProxyPrefix。
</proxy_prefix>

<post_allow>
預設：true
說明：設定允許／拒絕開放 POST(REST) 的 IP 來源。
<host>
預設：
192\.168\.[0-9]{1,3}\.[0-9]{1,3}
::ffff:192\.168\.[0-9]{1,3}\.[0-9]{1,3}
127\.0\.0\.1
::ffff:127\.0\.0\.1
::1
172\.17\.[0-9]{1,3}\.[0-9]{1,3}
::ffff:172\.17\.[0-9]{1,3}\.[0-9]{1,3}
</host>
</post_allow>

<frame_ancestors>
預設：無
說明：指定誰可以嵌入 OxOffice Online 的 iframe（oxoolwsd 與 WOPI host 總是允許），以空格分隔多個主機。
</frame_ancestors>

<connection_timeout_secs>
預設：30
說明：指定由 oxoolwsd 發起（如 WOPI 連線）的連線、傳送、接收等動作的逾時秒數。
</connection_timeout_secs>
</net>

<ssl>
說明：OxOffice Online 的 SSL 設定。
<enable>
預設：false
說明：設定是否要啟動 SSL 機制。
</enable>

<termination>
預設：true
說明：如果是透過代理伺服器設定連線，則此選項須設定為 true。
</termination>

<cert_file_path>
預設：/etc/oxool/cert.pem
說明：設定憑證檔的路徑，若是使用代理伺服器則不需變更，可使用代理伺服器的設定。
</cert_file_path>

<key_file_path>
預設：/etc/oxool/key.pem
說明：設定憑證金鑰的路徑，若是使用代理伺服器則不需變更，可使用代理伺服器的設定。
</key_file_path>

<ca_file_path>
預設：/etc/oxool/ca-chain.cert.pem
說明：設定憑證 ca 檔的路徑，若是使用代理伺服器則不需變更，可使用代理伺服器的設定。
</ca_file_path>

<cipher_list>
預設：ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH
說明：設定可接受的 OpenSSL 加密演算法清單。
</cipher_list>

<hpkp>
說明：啟用 HPKP。
<max_age>
預設：1000
說明：HPKP max-age 指令，以秒為單位，設定瀏覽器應該保留 pins 的時間。
</max_age>
<report_uri>
預設：空
說明：HPKP report-uri 指令，pin 的驗證錯誤回報 URL。
</report_uri>
<pins>
說明：要 pin 的金鑰的 Base64 編碼 SPKI 指紋。
<pin></pin>
</pins>
</hpkp>
</ssl>

<security>
說明：【警告】更改這些預設值可能會讓系統面臨重大風險。
<seccomp>
預設：true
說明：設定使用 seccomp 系統呼叫 filtering。
</seccomp>

<capabilities>
預設：true
說明：設定使用 chroot jails 的機制。
</capabilities>

<jwt_expiry_sec>
預設：1800
說明：管理介面的 JWT 權杖過期時間（以秒為單位）。
</jwt_expiry_sec>

<enable_macros_execution>
預設：false
說明：指定是否要執行巨集。這會啟用 Basic、Beanshell、JavaScript 與 Python 指令稿。若設定為 false，則下方的 macro_security_level 設定會被忽略。若設定為 true，則前述設定會用來指定巨集的安全層級。
</enable_macros_execution>

<macro_security_level>
預設：1
說明：巨集的安全層級。1（中等）必須在執行從未受信任的來源執行巨集前先進行確認。0（低，不建議）是所有巨集都可不經確認即執行。
</macro_security_level>

<enable_metrics_unauthenticated>
預設：false
說明：啟用時，/oxool/getMetrics 即不需要驗證。
</enable_metrics_unauthenticated>
</security>

<watermark>
說明：浮水印相關設定。
<editing>
預設：false
說明：若啟用，則會在編輯文件時顯示浮水印。
</editing>

<printing>
預設：false
說明：若啟用，則會在列印文件或將其匯出為 PDF 檔案時顯示浮水印。
</printing>

<opacity>
預設：0.2
說明：畫面上浮水印的不透明度，值可從 0.0 到 1.0。
</opacity>

<angle>
預設：45
說明：浮水印角度。
</angle>

<font>
預設：無
說明：字型名稱。
</font>

<color>
預設：#000000
說明：浮水印文字色彩。
</color>

<bold>
預設：false
說明：浮水印文字是否要為粗體。
</bold>

<italic>
預設：false
說明：浮水印文字是否要為義式斜體。
</italic>

<outline>
預設：false
說明：浮水印文字是否要變為中空。
</outline>

<shadow>
預設：false
說明：浮水印文字是否要帶有陰影。
</shadow>

<text>
預設：無
說明：輸入時要在畫面上顯示的浮水印文字。
</text>
</watermark>

<welcome>
說明：歡迎畫面的相關設定。
<enable>
預設：編譯時決定的參數
說明：控制是否要在新安裝及更新時對使用者顯示歡迎畫面。
</enable>

<enable_button>
預設：編譯時決定的參數
說明：決定歡迎畫面是否應該要有解釋性的按鈕而非關閉按鈕。
</enable_button>

<path>
預設：loleaflet/welcome
說明：歡迎畫面網頁的路徑。
</path>
</welcome>

<user_interface>
說明：編輯器使用者介面的相關設定。

<pdf_viewer_resolution_dpi>
預設：600
說明：檢視程式在繪製 PDF 內容時要使用的 DPI。
</pdf_viewer_resolution_dpi>
  
<use_integration_theme>
預設：false
說明：是否要使用來自 Nextcloud Office 等整合程式的佈景主題。
</use_integration_theme>
</user_interface>

<storage>
說明：不同後端儲存空間的連線設定。
<filesystem>
預設：false
說明：是否啟動讓 OxOffice Online 直接編輯本機檔案的機制，建議在正式佈署時確定更改為 false。

<wopi>
預設：true
說明：允許／拒絕 wopi storage，與 webdav 互斥。
<host>
預設：
true:
localhost
127\.0\.0\.1
10\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}
172\.1[6789]\.[0-9]{1,3}\.[0-9]{1,3}
172\.2[0-9]\.[0-9]{1,3}\.[0-9]{1,3}
172\.3[01]\.[0-9]{1,3}\.[0-9]{1,3}
192\.168\.[0-9]{1,3}\.[0-9]{1,3}
false:
192\.168\.1\.1

說明：設定 wopi host 的主機名稱或是 IP 位置，如果主機名稱或 IP 中包含了「.」，則需加入「\」跳脫字元，例如：原本是 www.ossii.com.tw，那麼在 wopi host 內需設定成為「www\.ossii\.com\.tw」。
</host>

<max_file_size>
預設：0
說明：可載入的最大文件大小（以位元組為單位），0 代表無限制。
</max_file_size>

<reuse_cookies>
預設：false
說明：若啟用，則會捕捉來自瀏覽器的 cookies，並在 WOPI 請求中設定。
</reuse_cookies>

<locking>
說明：鎖定相關設定。
 <refresh>
說明：設定應多常重新取得儲存伺服器的鎖，以秒為單位（預設為900秒，亦即15分鐘），設為 0 則不更新。
 </refresh>
</locking>
</wopi>

<webdav>
預設：false
說明：允許／拒絕 webdav storage，與 wopi 互斥。
<host>
預設：false: localhost
說明：設定 webdav host的主機名稱或是 IP 位置，如果主機名稱或 IP 中間包含了「.」，則需加入「\」跳脫字元，例如：原本是 www.ossii.com.tw，那麼在 webdav host 內需設定成為「www\.ossii\.com\.tw」。
</host>
</webdav>
<ssl>
說明：OxOffice Online 的 SSL 設定。
<as_scheme>
預設：true
說明：設定後，將會啟用專門針對 WOPI URI 結構的 SSL 來供儲存空間使用。
</as_scheme>
<enable>
預設：false
說明：設定是否要啟動 SSL 機制。
</enable>

<cert_file_path>
預設：/etc/oxool/cert.pem
說明：設定憑證檔的路徑，若是使用代理伺服器則不需變更，可使用代理伺服器的設定。
</cert_file_path>

<key_file_path>
預設：/etc/oxool/key.pem
說明：設定憑證金鑰的路徑，若是使用代理伺服器則不需變更，可使用代理伺服器的設定。
</key_file_path>

<ca_file_path>
預設：/etc/oxool/ca-chain.cert.pem
說明：設定憑證 ca 檔的路徑，若是使用代理伺服器則不需變更，可使用代理伺服器的設定。
</ca_file_path>

<cipher_list>
預設：ALL:!ADH:!LOW:!EXP:!MD5:@STRENGTH
說明：設定可接受的 OpenSSL 加密演算法清單。
</cipher_list>
</ssl>
</storage>

<tile_cache_persistent>
預設：true
說明：設定是否在相同文件的不同編輯 session 保留 tile cache。
</tile_cache_persistent>

<admin_console>
說明：OxOffice Online 網頁端管理介面設定參數，預設登入的連線位置為：http(s)://youroxoolip:9980/loleaflet/dist/admin/admin.html。
<enable>
預設：true
說明：啟用管理功能。
</enalbe>

<enable_pam>
預設：false
說明：啟用 PAM 使用者認證機制。
</enalbe_pam>

<username>
預設：admin
說明：設定管理介面的登入帳號，若啟用 PAM 機制則會忽略此設定。
</username>

<password>
預設：@administrator1
說明：設定管理介面的登入密碼。在多數平台上已被棄用，建議使用 PAM 或 oxoolconfig 設定安全的密碼。
</password>
</admin_console>

<monitors>
預設：空
說明：設定連線的伺服器位置。
</monitors>
```