사용자 가이드

Glasswall Conform은 추가 처리를 위한 표준을 충족하도록 PDF 파일을 사전 처리하도록 설계되었습니다. 시각적 콘텐츠를 추출하고 재구성하며, 완전한 Content Disarm and Reconstruction (CDR) 보호를 위해 Glasswall Embedded Engine과 함께 사용해야 합니다.

이 문서에서는 PDF 문서를 재구성하기 위해 Conform을 사용하는 방법과 함께, 명령줄 도구를 호출하기 위한 몇 가지 예제를 제공합니다.

설치

Conform은 터미널에서 접근할 수 있는 시스템 전체 명령으로 설치됩니다.

설치가 완료되면 glasswall_conform 명령을 시스템의 PATH에서 사용할 수 있습니다. 이 변경 사항을 적용하려면 터미널 세션을 다시 시작해야 할 수 있습니다.

Windows

Windows용 Conform은 .exe 설치 프로그램으로 배포됩니다. C:\Program Files (x86)\Glasswall Conform에 설치되며 이 폴더를 시스템 PATH에 추가합니다.

설치 프로그램을 실행하고 안내에 따라 Conform을 설치합니다:

.\glasswall-conform-1.1.0.exe

또는 자동화 또는 CI 환경을 위해 무인 설치할 수 있습니다:

.\glasswall-conform-1.1.0.exe /VERYSILENT

Linux

Linux용 Conform은 .rpm 및 .deb 패키지로 배포됩니다.

Both install files to /opt/glasswall_conform and create a symbolic link in /usr/local/bin to allow running glasswall_conform from the command line.

RPM(예: Rocky 9, Rocky 8)

sudo yum -y install ./glasswall_conform-1.1.0-1.x86_64.rpm

DEB (예: Ubuntu 24.04, Ubuntu 22.04)

sudo apt-get -y install ./glasswall-conform_1.1.0_amd64.deb

설정

glasswall_conform을 호출하기 전에 환경이 올바르게 설정되어 있는지 확인하십시오.

Embedded Engine을 사용하는 모드의 경우, --library-directory에 전달되는 디렉터리에는 Embedded Engine 바이너리가 포함되어 있어야 합니다. Conform은 시작 시 이를 확인하며, 해당 파일이 없으면 짧은 메시지를 표시하고 중지합니다.

Linux

Embedded Engine을 사용하는 처리 모드의 경우, LD_LIBRARY_PATH에 Embedded Engine이 포함된 디렉터리가 포함되도록 설정해야 합니다. 예를 들어 Embedded Engine 경로가 /home/azureuser/glasswall/Release-16.2.0인 경우, LD_LIBRARY_PATH를 일시적으로 다음과 같이 수정할 수 있습니다:

export LD_LIBRARY_PATH=/home/azureuser/glasswall/Release-16.2.0:$LD_LIBRARY_PATH

Ubuntu

Ubuntu 기반 시스템에서 libgthread-2.0.so.0: cannot open shared object file: No such file or directory 오류 메시지가 발생하는 경우, 다음 명령으로 필요한 패키지를 설치하여 해결할 수 있습니다:

DEBIAN_FRONTEND=noninteractive && apt update && apt install -y libglib2.0-0

Windows

Windows 종속성은 chocolatey를 사용하여 설치하는 것을 권장합니다.

모든 처리 모드에서 Microsoft Visual C++ Redistributable가 설치되어 있어야 합니다.

Embedded Engine을 사용하는 처리 모드의 경우:

PATH에는 Embedded Engine이 포함된 디렉터리가 설정되어 있어야 합니다. 예를 들어 Embedded Engine이 C:/glasswall/Release-16.2.0 경로에 있는 경우, PATH를 일시적으로 다음과 같이 수정할 수 있습니다:
```
SET "PATH=%PATH%;C:/glasswall/Release-16.2.0"
```
OpenSSL light 또는 OpenSSL이 설치되어 있어야 합니다.

chocolatey를 사용하여 vcredist140 및 openssl.light를 설치하는 Windows docker 설치 예시는 다음과 같습니다:

# escape=`
FROM mcr.microsoft.com/windows/servercore:ltsc2022

USER ContainerAdministrator
WORKDIR C:\temp\
SHELL ["powershell", "-Command", "$ErrorActionPreference = 'Stop'; $ProgressPreference = 'SilentlyContinue';"]

# Download and install Chocolatey, to install OpenSSL and Visual C++ Redistributable
RUN Invoke-WebRequest -Uri 'https://chocolatey.org/install.ps1' -OutFile 'install.ps1'; `
    ./install.ps1; ` 
    Remove-Item install.ps1; `
    Import-Module "$env:ChocolateyInstall/helpers/chocolateyProfile.psm1"; `
    choco install -y --fail-on-unfound --no-progress --stop-on-first-package-failure vcredist140; `
    choco install -y --fail-on-unfound --no-progress --stop-on-first-package-failure openssl.light;

라이선스

Glasswall Conform를 실행하려면 유효한 라이선스가 필요합니다. 라이선스 파일을 받으려면 [email protected]에 문의하세요.

--license 인수는 모든 처리 모드에서 사용할 수 있으며, 라이선스 파일의 직접 경로 또는 gwkey.lic 파일이 포함된 디렉터리 경로를 지정하는 데 사용됩니다.

Engine modes (engine, engine_memory): --license는 선택 사항입니다. 지정하지 않으면 Conform은 --library-directory에서 gwkey.lic 파일을 자동으로 검색합니다. 파일을 찾으면 해당 파일을 라이선스로 사용합니다. 찾지 못하면 오류가 발생합니다.
Conform-only modes (conform_only, conform_only_memory): 검색할 라이브러리 디렉터리가 없으므로 --license가 필수입니다.

라이선스가 없거나 유효하지 않거나 필요한 entitlement가 포함되어 있지 않으면 Conform은 오류 코드 2와 함께 종료됩니다.

  --license LICENSE      Path to the Glasswall Conform license file, or a directory containing 'gwkey.lic'.
                         Required for conform_only and conform_only_memory modes.
                         In engine modes, defaults to 'gwkey.lic' in the library directory if not specified.

처리 모드

Conform은 명령줄에서 실행되며 파일 처리를 위한 여러 processing modes를 제공합니다. glasswall_conform을 호출할 때 첫 번째 위치 인수는 처리 모드를 지정합니다. 사용 가능한 처리 모드는 다음과 같습니다:

engine: Engine을 사용하여 파일을 보호합니다. 규격에 맞지 않는 파일은 Conform이 재구성한 다음 Engine이 처리합니다.
conform_only: CDR 보호를 제공하지 않고 Conform만 사용하여 파일을 재구성합니다.
engine_memory: 표준 입력을 통해 base64로 인코딩된 파일을 받습니다. Engine을 사용하여 메모리에서 단일 파일을 보호합니다. 파일이 규격에 맞지 않으면 Conform을 사용해 재구성한 다음 Engine이 처리합니다. 처리된 파일은 표준 출력을 통해 반환되며, 오류가 발생하면 표준 오류를 통해 반환됩니다.
conform_only_memory: 표준 입력을 통해 base64로 인코딩된 파일을 받습니다. CDR 보호를 제공하지 않고 Conform만 사용하여 단일 파일을 재구성합니다. 재구성된 파일은 표준 출력을 통해 반환되거나, 오류는 표준 오류를 통해 반환됩니다.

사용 가능한 처리 모드를 표시하려면:

glasswall_conform -h

engine

이 처리 모드는 의도된 기본값이며 Glasswall CDR 기술을 사용해 파일을 정화합니다. Embedded Engine에 대한 액세스와 유효한 라이선스가 필요합니다.

이 처리 모드를 호출하는 예시는 다음을 참조하세요: 엔드 투 엔드 보호.

처리된 파일은 다음 세 가지 출력 하위 디렉터리 중 하나로 분류됩니다:

01_engine_success: Conform에 의한 재구성 없이 Embedded Engine에서 성공적으로 처리된 파일입니다.
02_conform_engine_success: 처음에는 Embedded Engine에서 처리할 수 없었지만, Conform으로 재구성한 후 Embedded Engine에서 성공적으로 처리된 PDF 파일입니다.
03_failure: Embedded Engine과 Conform 모두를 사용한 처리에 실패했거나, 사용자 지정 콘텐츠 관리 policy를 사용해 허용되지 않도록 설정된 콘텐츠를 포함한 파일입니다.

engine 처리 모드의 명령줄 인수를 표시하려면:

glasswall_conform engine -h

conform_only

이 처리 모드는 Embedded Engine을 사용하지 않고 파일을 재구성합니다. CDR 보호는 제공하지 않습니다.

이 처리 모드를 호출하는 예시는 다음을 참조하세요: CDR 보호 없이 파일 재구성

처리된 파일은 다음 두 가지 출력 하위 디렉터리 중 하나로 분류됩니다:

01_conform_success: Conform에 의해 성공적으로 재구성된 파일.
02_failure: Conform에 의해 재구성에 실패한 파일.

conform_only 처리 모드의 명령줄 인수를 표시하려면:

glasswall_conform conform_only -h

engine_memory

이 모드는 표준 입력을 통해 base64로 인코딩된 파일을 받아 Embedded Engine을 사용해 처리합니다. 파일이 규격에 맞지 않으면 Conform이 이를 재구성한 다음 Engine이 처리합니다. 최종 출력은 표준 출력을 통해 반환되며, 오류가 발생하면 표준 오류를 통해 반환됩니다. 디스크에는 어떤 파일도 기록되지 않습니다.

이 모드는 파일을 메모리에 보관하고 파일 시스템 입력 또는 출력에 의존하지 않는 시스템과 통합하는 데 이상적입니다.

이 처리 모드를 호출하는 예시는 다음을 참조하세요: 디스크에서 읽거나 디스크에 쓰지 않고 메모리에서 파일 처리.

engine_memory 처리 모드의 명령줄 인수를 표시하려면:

glasswall_conform engine_memory -h

선택적 인수 --file-name을 사용하여 메모리 내 파일의 이름을 지정할 수 있습니다. 이는 로그와 후처리 요약을 작성할 때 사용되며, 지정하지 않으면 기본값으로 base64 인코딩된 데이터의 처음 8자가 사용됩니다.

conform_only_memory

이 모드는 표준 입력을 통해 base64로 인코딩된 파일을 받아 Conform만 사용하여 재구성합니다(CDR 보호 없음). 재구성된 파일은 표준 출력을 통해 반환되며, 오류가 발생하면 표준 오류를 통해 반환됩니다. 디스크에는 어떤 파일도 기록되지 않습니다.

이 처리 모드를 호출하는 예시는 다음을 참조하세요: 디스크에서 읽거나 디스크에 쓰지 않고 메모리에서 파일 처리.

conform_only_memory 처리 모드의 명령줄 인수를 표시하려면:

glasswall_conform conform_only_memory -h

테스트

Conform 평가를 위한 PDF 테스트 파일 데이터세트는 요청 시 제공됩니다. Kiteworks를 통해 테스트 파일에 대한 액세스를 요청하려면 당사에 문의해 주세요.

예제

Examples

종단 간 보호

이 예제는 engine 처리 모드를 가장 기본적인 수준에서 사용하는 방법을 보여줍니다.

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0

예제 입력 디렉터리:

/home/azureuser/input_files
    conforming_docx.docx
    conforming_pdf.pdf
    corrupt_docx.docx
    nonconforming_pdf.pdf
    unsupported_filetype.txt

처리 후 예제 출력 디렉터리:

/home/azureuser/output_files
├───01_engine_success
│       conforming_docx.docx
│       conforming_pdf.pdf
│
├───02_conform_engine_success
│       nonconforming_pdf.pdf
│
└───03_failure
        corrupt_docx.docx
        unsupported_filetype.txt

하위 디렉터리 이름은 다음 인수를 사용하여 사용자 지정할 수 있습니다:

--engine-success-path: 선택 사항. Conform에 의한 재구성 없이 Embedded Engine에서 성공적으로 처리된 파일의 출력 하위 디렉터리 이름입니다. 기본값 01_engine_success
--conform-success-path: 선택 사항. 처음에는 Embedded Engine에서 처리할 수 없었지만 Conform으로 재구성한 후 Embedded Engine에서 성공적으로 처리된 파일의 출력 하위 디렉터리 이름입니다. 기본값 02_conform_engine_success
--failure-path: 선택 사항. Embedded Engine과 Conform 모두를 사용한 처리에 실패한 파일의 출력 하위 디렉터리 이름입니다. 기본값 03_failure

Conform을 사용해 파일을 재구성했는지 여부와 관계없이, 성공적으로 보호된 모든 파일을 동일한 출력 디렉터리에 기록하려면 동일한 성공 하위 디렉터리 경로에 파일을 쓰도록 지정할 수 있습니다. 예:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --engine-success-path success --conform-success-path success --failure-path failure

처리 후 잘린 터미널 출력 예:

Glasswall Conform processed 3/5 files (60.00%)
Glasswall Conform failed to process 2/5 files. (40.00%)
Exceptions:
  PdfExtractionError (Total: 2)
    - 1x Unable to extract content from PDF: '/home/azureuser/input_files/corrupt_docx.docx'
    - 1x Unable to extract content from PDF: '/home/azureuser/input_files/unsupported_filetype.txt'
2024-11-06 14:28:50.242 glasswall_conform.config.logging INFO     engine_mode                   Total elapsed time: 5.55 seconds

CDR 보호 없이 파일 재구성

conform_only 처리 모드는 CDR 보호를 제공하지 않으며, 입력 디렉터리 -i, 출력 디렉터리 -o, 그리고 --license 경로가 필요합니다. conform_only를 참조하세요.

glasswall_conform conform_only -i /home/azureuser/input_files -o /home/azureuser/output_files --license /home/azureuser/gwkey.lic

메모리에서 파일 처리하기(디스크에서 읽거나 디스크에 쓰지 않음)

engine_memory 및 conform_only_memory 처리 모드를 사용하면 I/O를 사용하지 않고 메모리에서 파일을 처리할 수 있습니다.

처리가 성공하면 base64로 인코딩된 출력 파일이 표준 출력으로 반환됩니다. 처리 중 오류가 발생하면 오류 메시지와 후처리 요약이 표준 오류에 기록됩니다.

시간 초과 실패에 대한 표준 오류 예시:

Error: Processing failed for file: 'hus11976.pdf'. Summary: {'conform_version': '0.11.2', 'operating_system': 'Windows', 'summary_verbosity': 'all', 'processing_rates': {'success': 0.0, 'failure': 100.0}, 'processing_counts': {'success': 0, 'failure': 1, 'total': 1}, 'processing_time': {'elapsed_seconds': 8.25, 'files_per_sec': 0.12, 'secs_per_file': 8.25}, 'processing_arguments': {'mode': 'engine_memory', 'library_directory': 'C:/azure/sdk.editor/2.1394.0/build-sdk-editor-windows-amd64-dev_license', 'cautious_mode': False, 'max_workers': 1, 'timeout_seconds': 5.0, 'memory_limit_gib': 11.96, 'function_name': 'protect_file', 'content_management_policy': None}, 'processing_success': [], 'processing_failure': [{'file_name': 'hus11976.pdf', 'timed_out': True, 'out_of_memory': False, 'max_memory_used_in_gib': 0.32227325439453125, 'elapsed_time': 5.0007593631744385, 'exception': 'TimeoutError()', 'success': False}]}

기본 사용 예시:

메모리에 있는 PDF 파일의 base64 인코딩 문자열을 직접 glasswall_conform에 파이프로 전달

echo "U29tZUJhc2U2NERhdGE=" | glasswall_conform.exe engine_memory -l "C:/azure/sdk.editor/2.1394.0" --file-name "SomeBase64Data"

또는 subprocess를 통해 Python 사용

import base64
import os
import subprocess

# File in memory, for this example simply loaded from a file path
file_path = r"C:\conform\input\Set-08-016599.pdf"
with open(file_path, "rb") as f:
    file_bytes = f.read()
# Convert to base64-encoded string
encoded_file_bytes = base64.b64encode(file_bytes).decode("utf-8")

file_name = os.path.basename(file_path)
command = " ".join(
    [
        "glasswall_conform",
        "engine_memory",
        '-l "C:/azure/sdk.editor/2.1394.0"',
        f'--file-name "{file_name}"',  # Optional, used for summary and logs
        f'--summary-path "C:/conform/summary_{file_name}.json"',  # Optional
        '--watermark "Processed for security: Visual elements may vary"',  # Optional
    ]
)
# Run Conform with the base64-encoded string as an input
result = subprocess.run(command, input=encoded_file_bytes, text=True, capture_output=True, shell=True)

if result.stderr:
    # Conform failed, handle error gracefully here
    print(result.stderr)
else:
    # Conform succeeded, convert the conformed file from base64 to bytes
    conformed_file_bytes = base64.b64decode(result.stdout)
    # Do something with the conformed file bytes, e.g. write to a file
    with open("conformed_file.pdf", "wb") as f:
        f.write(conformed_file_bytes)

Similarly, conform_only_memory mode can be used by replacing engine_memory in the above examples, omitting the -l argument and specifying --license as it is required for this mode.

고속 모드와 신중 모드

고속 모드는 Conform의 기본 처리 모드입니다. 가장 빠른 처리 속도와 PDF 파일에 대한 최상의 시각적 품질을 제공하지만, PDF 사양에 대한 매우 엄격한 준수가 필요한 시나리오에는 적합하지 않을 수 있습니다.

고속 모드가 비활성화되어 있거나 파일을 처리할 수 없는 경우, Conform은 자동으로 신중 모드로 전환됩니다. 이 모드는 내장 글꼴을 대체하여 규정 준수와 위험 감소를 우선시하며, 이를 통해 사용자 지정 또는 알 수 없는 글꼴과 관련된 문제를 완화하는 데 도움이 됩니다. 신중 모드는 이미지 품질 저하 또는 누락, 일관되지 않은 글꼴 크기, 텍스트 누락과 같이 시각적 충실도가 낮아지는 결과를 초래할 수 있습니다.

fast mode를 비활성화하는 것은 시각적 충실도를 희생하더라도 PDF 표준을 매우 엄격하게 준수해야 하는 경우에만 권장됩니다.
cautious mode를 비활성화하는 것은 내장 글꼴 보존이 필수적이거나, Conform이 더 넓은 범위의 PDF를 성공적으로 처리할 수 있는 능력보다 시각적 모양이 더 중요한 경우에만 권장됩니다.

fast mode는 선택적 --disable-fast-mode 명령줄 인수를 사용하여 비활성화할 수 있습니다. cautious mode는 선택적 --disable-cautious-mode 명령줄 인수를 사용하여 비활성화할 수 있습니다.

Conform이 fast mode를 사용하여 파일을 성공적으로 처리하는 경우:

가장 빠른 처리 속도.
가장 뛰어난 시각적 표현.
사용자 지정 포함 글꼴은 대체되지 않습니다.
PDF 표준에 대한 매우 엄격한 준수가 필요한 시나리오에는 적합하지 않을 수 있습니다.

Conform이 cautious mode 대체 처리를 사용하는 경우:

처리 속도가 더 느립니다.
In a small number of cases, may result in reduced visual appearance, such as:
- 이미지 및 그래픽이 손상되거나 누락될 수 있습니다.
- 텍스트 모양의 차이(예: 크기, 글꼴 스타일 또는 간격).
- 알 수 없는 포함 글꼴이 사용 중인 경우 텍스트가 누락될 수 있습니다.
사양을 더 엄격하게 준수하여 PDF를 처리합니다.
사용자 지정 포함 글꼴을 신뢰할 수 있는 글꼴로 대체합니다.

Glasswall Python Wrapper 기능

engine 처리 모드에서는 Glasswall Python Wrapper의 protect_file 함수가 기본적으로 Embedded Engine을 사용해 파일을 처리하는 데 사용됩니다. 이는 선택적 -f 명령줄 인수를 사용하여 변경할 수 있습니다.

A default sanitise content management policy is applied if a policy file is not specified using the optional -c command line argument.

필수 -l 명령줄 인수는 Embedded Engine이 포함된 디렉터리를 가리켜야 합니다.

다음 인수는 Glasswall Python Wrapper와 관련됩니다:

  -l LIBRARY_DIRECTORY, --library-directory LIBRARY_DIRECTORY
                        Required. Path to directory containing the Embedded Engine.
  -f FUNCTION_NAME, --function-name FUNCTION_NAME
                        Optional. Glasswall Python Wrapper function name to call during multiprocessing, such as 'protect_file' or 'export_file'. Default: 'protect_file'.
  -c CONTENT_MANAGEMENT_POLICY, --content-management-policy CONTENT_MANAGEMENT_POLICY
                        Optional. Path to Embedded Engine content management policy file. If not provided, the default 'sanitise' policy is used.
  --log-level-console-wrapper {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}
                        Optional. Set logging level for writing Glasswall Python Wrapper logs to console. Default INFO.

예:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 -f protect_file -c /home/azureuser/glasswall/config.xml

멀티프로세싱

모든 처리 모드는 파일을 동시에 효율적으로 처리하기 위해 Glasswall Python Wrapper의 GlasswallProcessManager를 활용합니다.

다음 인수는 멀티프로세싱과 관련됩니다:

  -w MAX_WORKERS, --max-workers MAX_WORKERS
                        Optional. Maximum workers for multiprocessing, 0=auto. Default: 0.
  -t TIMEOUT_SECONDS, --timeout-seconds TIMEOUT_SECONDS
                        Optional. Multiprocessing timeout per file in seconds. Default: 180.
  -m MEMORY_LIMIT_GIB, --memory-limit-gib MEMORY_LIMIT_GIB
                        Optional. Multiprocessing memory limit per file in GiB, 0=auto (4GiB min, worker distributed max). Default: 0.

예:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 -t 300 -m 12

로깅

Conform 및 Glasswall Python Wrapper의 기본 logging level은 INFO입니다. 다음 인수는 logging과 관련됩니다:

  --log-level-console {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}
                        Optional. Set logging level for writing logs to console. Default INFO.
  --log-level-file {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}
                        Optional. Set logging level for writing logs to file. If not provided, logs will not be written to file.
  --log-path LOG_PATH   Optional. Path to output log file. Default is a timestamp-named file located at: '%TEMP%/glasswall_conform/logs'.
  --log-level-console-wrapper {CRITICAL,ERROR,WARNING,INFO,DEBUG,NOTSET}
                        Optional. Set logging level for writing Glasswall Python Wrapper logs to console. Default INFO.

대부분의 logging을 억제하려면:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --log-level-console CRITICAL --log-level-console-wrapper CRITICAL

콘텐츠 처리율 사용자 지정

이 섹션은 fast mode가 비활성화된 경우에만 적용됩니다.

기본적으로 Conform은 원본 문서 콘텐츠의 일부만 성공적으로 처리된 경우에도 가능하면 출력 파일을 생성합니다. 이러한 동작이 항상 바람직한 것은 아니며, 각 문서 내의 서로 다른 유형의 콘텐츠에 대해 사용자 지정할 수 있습니다.

Conform은 가능한 한 많은 텍스트가 원본 문서에서 conform된 문서로 전달되도록, 형식이 잘못되었거나 손상되었거나 지원되지 않는 텍스트 콘텐츠를 처리할 때 "best guesses"를 사용합니다. 예를 들어 텍스트의 stroke colour가 형식이 잘못되었거나 지원되지 않는 색상 형식인 경우, 출력 문서에서는 stroke colour가 기본적으로 검은색으로 설정된 상태로 텍스트가 유지됩니다.

이러한 "best guess" 접근 방식은 원본과 유사하게 보이는 텍스트를 생성할 수 있으며, 경우에 따라서는 보이지 않지만 출력 문서에는 여전히 존재하는 텍스트가 될 수도 있습니다. best guess가 원본 문서와 동일한 방식으로 텍스트를 처리한다고 보장할 수 없으므로, 처리율에는 이것이 완전히 처리되지 않은 콘텐츠로 반영됩니다. 따라서 텍스트의 처리율이 낮다고 해서 best guesses가 적용될 때 문서가 시각적으로 다르게 보인다는 의미는 항상 아닙니다.

콘텐츠 처리 시 최소 성공률을 설정하는 데 사용할 수 있는 인수는 세 가지입니다:

  --text-min-success-rate TEXT_MIN_SUCCESS_RATE
                        Optional. The minimum success rate for processing text. Default: 0.0.
  --image-min-success-rate IMAGE_MIN_SUCCESS_RATE
                        Optional. The minimum success rate for processing images. Default: 0.0.
  --graphic-min-success-rate GRAPHIC_MIN_SUCCESS_RATE
                        Optional. The minimum success rate for processing graphics. Default: 0.0.

최소 콘텐츠 처리율 값이 충족되지 않으면 해당 파일의 처리는 실패로 간주되며 출력 파일은 기록되지 않습니다.

워터마킹

워터마킹은 기본적으로 비활성화되어 있지만 --watermark 인수를 사용하여 활성화할 수 있습니다. 텍스트는 글꼴 크기 12의 반투명한 짙은 회색으로 추가됩니다. 워터마크는 일반적으로 문서의 오른쪽 상단에 배치되지만, 페이지에 적용된 회전에 따라 방향이 달라질 수 있습니다. 현재 워터마크의 최대 텍스트 길이는 256자입니다.

  --watermark WATERMARK
                        Optional. Adds a watermark to each page of the reconstructed document. Default '' (disabled).

예:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --watermark "Glasswall Conform"

CID 억제

이 섹션은 fast mode가 비활성화된 경우에만 적용됩니다.

PDF에서는 일부 글꼴이 대규모 문자 집합을 관리하기 위해 CID (Character Identifier)라는 시스템을 사용합니다. 새 PDF를 구성할 때 도구가 처리할 수 없는 문자를 만나면 기본 물음표 문자 (?)로 대체합니다. --suppress-cid 인수를 사용하여 PDF에서 처리 불가능한 CID가 표시되는 방식을 조정할 수 있습니다:

  --suppress-cid SUPPRESS_CID
                        Optional. Replace CID metadata that may be printed to the visual layer due to font array omissions with the supplied string, with placeholder text.
                        Glasswall Conform restricts the processing of PDFs to only known secure fonts. This is a deliberate security feature to make the PDF conform safely. Default '■'.

예:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --suppress-cid "?"

글꼴 대체

이 섹션은 fast mode가 비활성화된 경우에만 적용됩니다.

Conform는 기본 14개 Type1 글꼴과 Cambria 글꼴의 bold, italic 및 bold italic 변형을 지원합니다. Conform는 일부 사용자 지정 글꼴도 지원합니다.

기본 14개 Type1 글꼴은 다음과 같습니다:

Courier, Courier-Bold, Courier-Oblique, Courier-BoldOblique
Helvetica, Helvetica-Bold, Helvetica-Oblique, Helvetica-BoldOblique
Times-Roman, Times-Bold, Times-Italic, Times-BoldItalic
Symbol
ZapfDingbats

지원되지 않는 임베디드 글꼴은 Cambria 글꼴로 대체될 수 있습니다. Cambria가 임베디드 글꼴의 글리프를 지원하지 않으면 해당 문자는 억제됩니다. 이에 대한 자세한 내용은 CID 억제를 참조하세요.

기본적으로 일반적으로 임베디드되는 일부 sans serif 글꼴은 시각적 유사성을 위해 Cambria 대신 Helvetica로 대체됩니다. 이 기능과 기타 글꼴 대체 기능은 다음 인수를 사용하여 수정할 수 있습니다:

  --disable-base-14-fonts
                        Optional. Disable matching embedded fonts to base 14 fonts.
                        This will result in more fonts being replaced by the fallback font, Cambria. Default False.
  --disable-custom-fonts
                        Optional. Disable matching embedded fonts to custom fonts.
                        This will result in lower support for custom embedded fonts, and more fonts being replaced by the fallback font, Cambria. Default False.
  --disable-sans-serif-replacement
                        Optional. Disable replacing some sans serif fonts with Helvetica instead of the fallback font, Cambria.
                        This will result in some replaced sans serif fonts looking more visually different when compared to the original file. Default False.

예:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --disable-custom-fonts

파일 포함 및 제외 필터링

Conform에서는 포함 및 제외 필터를 사용하여 입력 디렉터리의 어떤 파일을 처리할지 추가로 제어할 수 있습니다. 이러한 필터를 사용하면 명령줄에서 직접 기본적인 Unix 셸 스타일 와일드카드를 사용해 처리하거나 무시할 파일을 지정할 수 있습니다. 파일이 포함 규칙과 제외 규칙에 모두 일치하면 제외됩니다.

기본적으로 --include-files 및 --exclude-files 인수가 생략되면 Conform은 입력 디렉터리에 있는 모든 파일을 처리합니다.

다음 인수는 파일 포함 및 제외와 관련됩니다:

  --include-files INCLUDE_FILES
                        Optional. Can be either a path to a file containing file paths/patterns or a semicolon-separated list of patterns (e.g. '*.pdf;*/SET_03/*'). Only matching files will be processed.   
                        If None, all files are included. Default: None.
  --exclude-files EXCLUDE_FILES
                        Optional. Can be either a path to a file containing file paths/patterns or a semicolon-separated list of patterns. Any matching files will be excluded from processing. If None, no   
                        files are excluded. Default: None.

다음 표는 사용할 수 있는 몇 가지 패턴의 예를 보여줍니다:

패턴	의미	예	일치	일치하지 않음
`*`	모든 항목과 일치	`*.pdf`	`file.pdf`, `report.pdf`	`file.docx`
`?`	임의의 단일 문자와 일치	`file_?.pdf`	`file_1.pdf`, `file_A.pdf`	`file_10.pdf`
`[seq]`	`seq`의 임의의 문자 하나와 일치	`file_[AB].pdf`	`file_A.pdf`, `file_B.pdf`	`file_C.pdf`
`[!seq]`	Matches any character not in `seq`	`file_[!AB].pdf`	`file_C.pdf`, `file_D.pdf`	`file_A.pdf`, `file_B.pdf`

대소문자 구분 고려 사항

파일 이름은 Linux에서는 대소문자를 구분하지만 Windows에서는 대소문자를 구분하지 않습니다. 이는 서로 다른 운영 체제에서 파일 경로나 패턴이 해석되는 방식에 영향을 줍니다.

Linux에서는 report.pdf와 Report.pdf가 서로 다른 파일로 처리됩니다.
Windows에서는 둘 다 동일한 파일로 간주됩니다.

권장 사항: 플랫폼 전반에서 일관성을 보장하려면 파일 이름과 패턴에서 일관된 대소문자 사용을 적용하세요. 여러 환경에서 작업하는 경우, 불일치를 방지하기 위해 적절한 곳에 와일드카드 패턴(*)을 사용하는 것을 고려하세요.

단일 파일 포함 처리

--include-files로 단일 파일을 지정하는 경우, Conform은 먼저 제공된 값이 디스크상의 파일인지 확인하며, 파일이 아니면 해당 값은 패턴으로 처리된다는 점에 유의하세요.

잠재적 문제: 사용자가 다음과 같이 지정하면:

--include-files "/home/azureuser/input_files/first.pdf"

Conform은 /home/azureuser/input_files/first.pdf가 파일로 존재함을 확인하고, 여러 경로 또는 패턴이 포함된 목록 파일로서 이를 읽으려고 시도합니다.

해결 방법: 이것이 단일 파일에 대한 패턴임을 명시적으로 나타내려면 끝에 세미콜론을 추가하세요:

--include-files "/home/azureuser/input_files/first.pdf;"

이렇게 하면 Conform이 해당 경로를 목록 파일이 아니라 패턴으로 처리합니다.

특정 PDF 파일 포함

파일 이름에 "report"가 포함된 PDF만 처리하려면:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --include-files "*report*.pdf"

결과: annual_report.pdf, summary_report_2023.pdf 등과 같은 파일만 처리됩니다.

특정 PDF 파일 제외

이름에 "draft"가 포함된 파일을 제외하고 모든 PDF를 처리하려면:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --exclude-files "*draft*.pdf"

결과: proposal_draft.pdf 및 internal_draft_v2.pdf 같은 파일을 제외한 모든 PDF가 처리됩니다.

전체 디렉터리 제외

/home/azureuser/input_files/archive/ 내부의 모든 파일을 제외하려면:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --exclude-files "*/archive/*"

결과: /home/azureuser/input_files/archive/ 내부의 모든 항목이 건너뛰어집니다.

포함 및 제외 함께 사용

파일이 포함 규칙과 제외 규칙에 모두 일치하면 제외됩니다.

SET_03의 모든 파일을 처리하되, "error_log"를 포함하는 파일은 제외하려면:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --include-files "*/SET_03/*" --exclude-files "*error_log*"

결과: SET_03/의 파일만 처리되며, 파일 이름에 "error_log"가 포함된 파일은 예외입니다.

대규모 목록에 파일 사용

더 복잡한 필터링을 위해, 패턴이나 절대 파일 경로를 직접 지정하는 대신 여러 패턴 또는 절대 파일 경로가 포함된 파일을 제공할 수 있습니다.

포함 목록 파일을 사용하는 예:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --include-files "include_list.txt"

include_list.txt 예:

*/SET_03/*.pdf
*reports_2023_*.pdf
/home/azureuser/input_files/SET_02/splat.pdf

결과: SET_03/의 파일, reports_2023_를 포함하는 파일, 그리고 특정 파일 /home/azureuser/input_files/SET_02/splat.pdf만 처리합니다.

출력 파일 구조 및 분류

The directory structure for output files can be customised for both the engine and conform_only processing modes using the --output-structure command line argument.

  --output-structure {categorised,mirrored}
                        Optional. Defines the directory structure of output files. 'categorised' organises output files into subdirectories based on processing status ('engine_success', 'conform_success', 'failure').
                        'mirrored' places successfully processed output files directly in the output directory, maintaining the original input directory structure, and failed files will not be copied. Default: categorised.   

생략하면 기본 categorised 구조가 사용됩니다. 카테고리 하위 디렉터리 이름을 사용자 지정할 수 있는 추가 옵션도 제공됩니다:

--engine-success-path: 선택 사항. Conform에 의한 재구성 없이 Embedded Engine에서 성공적으로 처리된 파일의 출력 하위 디렉터리 이름입니다. 기본값 01_engine_success
--conform-success-path: 선택 사항. 처음에는 Embedded Engine에서 처리할 수 없었지만 Conform으로 재구성한 후 Embedded Engine에서 성공적으로 처리된 파일의 출력 하위 디렉터리 이름입니다. 기본값 02_conform_engine_success
--failure-path: 선택 사항. Embedded Engine과 Conform 모두를 사용한 처리에 실패한 파일의 출력 하위 디렉터리 이름입니다. 기본값 03_failure

`categorised` 출력 구조 예

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0

예제 입력 디렉터리:

/home/azureuser/input_files
    conforming_docx.docx
    conforming_pdf.pdf
    corrupt_docx.docx
    nonconforming_pdf.pdf
    unsupported_filetype.txt

처리 후 예제 출력 디렉터리:

/home/azureuser/output_files
├───01_engine_success
│       conforming_docx.docx
│       conforming_pdf.pdf
│
├───02_conform_engine_success
│       nonconforming_pdf.pdf
│
└───03_failure
        corrupt_docx.docx
        unsupported_filetype.txt

categorised 출력 구조를 사용할 때, Conform이 파일 재구성에 사용되었는지 여부와 관계없이 성공적으로 보호된 모든 파일을 동일한 출력 디렉터리에 기록하려면, 파일을 동일한 성공 하위 디렉터리 경로에 기록하도록 지정할 수 있습니다. 예:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --engine-success-path success --conform-success-path success --failure-path failure

`mirrored` 출력 구조 예

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --output-structure mirrored

예제 입력 디렉터리:

/home/azureuser/input_files
    conforming_docx.docx
    conforming_pdf.pdf
    corrupt_docx.docx
    nonconforming_pdf.pdf
    unsupported_filetype.txt

처리 후 예제 출력 디렉터리:

/home/azureuser/output_files
    conforming_docx.docx
    conforming_pdf.pdf
    nonconforming_pdf.pdf

후처리 요약

기본적으로 Conform이 파일 처리를 완료한 후 요약이 작성됩니다. 이 요약은 각 파일의 반환 상태, 처리 시간, 메모리 사용량과 같은 자세한 정보를 제공합니다. --summary-verbosity 인수는 요약에 포함될 파일을 제어합니다. 이 설정은 로깅 수준과는 별개이며 자세한 로그 출력에는 영향을 주지 않습니다.

사용 가능한 옵션

all (기본값) - 성공적으로 처리된 파일과 실패한 파일을 모두 포함합니다.
failure - 실패한 파일만 포함합니다.
success - 성공적으로 처리된 파일만 포함합니다.
none - 요약 출력을 완전히 비활성화합니다.

--summary-path 인수를 사용하면 요약을 터미널에 표시하는 대신 JSON 파일로 디스크에 기록할 수 있습니다.

요약 출력에 실패한 파일만 포함하는 예:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --summary-verbosity failure --summary-path /home/azureuser/conform_summary.json

요약 출력을 완전히 비활성화하는 예:

glasswall_conform engine -i /home/azureuser/input_files -o /home/azureuser/output_files -l /home/azureuser/glasswall/Release-16.2.0 --summary-verbosity none --summary-path /home/azureuser/conform_summary.json

예시 요약 JSON 출력(Windows):

{
    "conform_version": "0.10.1",
    "operating_system": "Windows",
    "summary_verbosity": "all",
    "processing_rates": {
        "success": 50.0,
        "failure": 50.0
    },
    "processing_counts": {
        "success": 2,
        "failure": 2,
        "total": 4
    },
    "processing_time": {
        "elapsed_seconds": 43.61,
        "files_per_sec": 0.09,
        "secs_per_file": 10.9
    },
    "processing_arguments": {
        "mode": "engine",
        "input_directory": "C:\\conform\\input",
        "output_directory": "C:\\conform\\output",
        "library_directory": "C:\\azure\\sdk.editor\\2.1394.0",
        "cautious_mode": false,
        "max_workers": 3,
        "timeout_seconds": 180,
        "memory_limit_gib": 4.35,
        "function_name": "protect_file",
        "content_management_policy": null,
        "include_files": null,
        "exclude_files": null,
        "output_structure": "categorised"
    },
    "processing_success": [
        {
            "input_file": "C:\\conform\\input\\pal1.bmp",
            "output_file": "C:\\conform\\output\\01_engine_success\\pal1.bmp",
            "engine_status": "OK(0)",
            "max_memory_used_in_gib": 0.11124420166015625,
            "elapsed_time": 0.9149298667907715,
            "success": true
        },
        {
            "input_file": "C:\\conform\\input\\Set-08-016599.pdf",
            "output_file": "C:\\conform\\output\\02_conform_engine_success\\Set-08-016599.pdf",
            "engine_status": "GeneralFail(-1)",
            "engine_GW2FileErrorMsg": "[FAILURE_LOG_SEM_FONTS_0021897368] Key /FirstChar must be present in a Type 1 Font dictionary other than for standard 14. fonts.",
            "engine_conform_fast_status": "GeneralFail(-1)",
            "engine_conform_fast_GW2FileErrorMsg": "[FAILURE_LOG_SEM_FONTS_0021897368] Key /FirstChar must be present in a Type 1 Font dictionary other than for standard 14. fonts.",
            "engine_conform_cautious_status": "OK(0)",
            "max_memory_used_in_gib": 0.22198104858398438,
            "elapsed_time": 1.8940067291259766,
            "success": true
        }
    ],
    "processing_failure": [
        {
            "input_file": "C:\\conform\\input\\pal1_corrupt.bmp",
            "engine_status": "FileTypeUnknown(-7)",
            "engine_GW2FileErrorMsg": "Unable to determine file type",
            "engine_conform_fast_status": "PdfFastProcessError()",
            "engine_conform_cautious_status": "PdfExtractionError(Unable to extract content from PDF: 'C:\\conform\\input\\pal1_corrupt.bmp')",
            "exit_code": 0,
            "timed_out": false,
            "out_of_memory": false,
            "max_memory_used_in_gib": 0.13513565063476562,
            "elapsed_time": 0.8690056800842285,
            "success": false
        },
        {
            "input_file": "C:\\conform\\input\\Straw120556398.pdf",
            "timed_out": false,
            "out_of_memory": true,
            "max_memory_used_in_gib": 4.3571624755859375,
            "elapsed_time": 41.976775884628296,
            "exception": "MemoryError()",
            "success": false
        }
    ]
}

설치​

Windows​

Linux​

RPM(예: Rocky 9, Rocky 8)​

DEB (예: Ubuntu 24.04, Ubuntu 22.04)​

설정​

Linux​

Ubuntu​

Windows​

라이선스​

처리 모드​

engine​

conform_only​

engine_memory​

conform_only_memory​

테스트​

예제​

종단 간 보호​

CDR 보호 없이 파일 재구성​

메모리에서 파일 처리하기(디스크에서 읽거나 디스크에 쓰지 않음)​

고속 모드와 신중 모드​

Glasswall Python Wrapper 기능​

멀티프로세싱​

로깅​

콘텐츠 처리율 사용자 지정​

워터마킹​

CID 억제​

글꼴 대체​

파일 포함 및 제외 필터링​

대소문자 구분 고려 사항​

단일 파일 포함 처리​

특정 PDF 파일 포함​

특정 PDF 파일 제외​

전체 디렉터리 제외​

포함 및 제외 함께 사용​

대규모 목록에 파일 사용​

출력 파일 구조 및 분류​

categorised 출력 구조 예​

mirrored 출력 구조 예​

후처리 요약​

설치

Windows

Linux

RPM(예: Rocky 9, Rocky 8)

DEB (예: Ubuntu 24.04, Ubuntu 22.04)

설정

Linux

Ubuntu

Windows

라이선스

처리 모드

engine

conform_only

engine_memory

conform_only_memory

테스트

예제

종단 간 보호

CDR 보호 없이 파일 재구성

메모리에서 파일 처리하기(디스크에서 읽거나 디스크에 쓰지 않음)

고속 모드와 신중 모드

Glasswall Python Wrapper 기능

멀티프로세싱

로깅

콘텐츠 처리율 사용자 지정

워터마킹

CID 억제

글꼴 대체

파일 포함 및 제외 필터링

대소문자 구분 고려 사항

단일 파일 포함 처리

특정 PDF 파일 포함

특정 PDF 파일 제외

전체 디렉터리 제외

포함 및 제외 함께 사용

대규모 목록에 파일 사용

출력 파일 구조 및 분류

`categorised` 출력 구조 예

`mirrored` 출력 구조 예

후처리 요약