일반적인 GCDS 문제해결하기

다음은 Google Cloud 디렉터리 동기화(GCDS)를 구성하는 동안 발생할 수 있는 문제를 해결하는 방법입니다.

로그 분석기 사용해 보기

이 도구에 로그를 제출하면 짧은 시간 내에 대부분의 문제를 파악할 수 있습니다.

Google 관리 콘솔 도구 상자 로그 분석기에 추적 로그(압축되지 않은 파일 또는 ZIP 파일로)를 제출하세요.
고급 로그 분석을 수행하려면 압축되지 않은 파일을 로그 분석기 2에 제출하세요.

추적 수준 로깅을 사용 설정하는 방법에 대해 자세히 알아보세요.

설정 및 구성

섹션 열기 | 모두 접고 상단으로 이동하기

구성 관리자를 사용하여 구성 문제 해결하기

동기화를 실행하는 중에 문제가 발생하는 경우 구성 관리자의 구성 정보가 올바른지 확인하고 어떤 테스트가 실패하는지 기록하세요.

구성 관리자에서 동기화를 구성하는 데 사용 중인 XML 파일을 엽니다
LDAP 연결 페이지에서 연결 테스트를 클릭하여 LDAP 서버와 연결할 수 있는지 확인합니다.
알림 페이지에서 알림 테스트를 클릭하여 테스트 알림을 보낼 수 있는지 확인합니다.
동기화 페이지에서 동기화 시뮬레이션을 클릭하여 모든 필수 입력란을 작성했는지와 동기화가 실행되는지 확인합니다.

API 요청에 전체 HTTP 로깅을 사용 설정하려면 어떻게 해야 하나요?

드물기는 하지만 Google Cloud 지원에서 GCDS에 추적 수준 로그 기록 사용 설정 이외에 전체 HTTP 로그 기록을 사용 설정하도록 요청할 수 있습니다. 전체 HTTP 로그 기록은 GCDS에 의한 정확한 API 요청과 Google API에서 제공한 응답을 보는 데 사용됩니다.

중요: 전체 HTTP 로그에 매우 민감한 정보가 포함될 수 있습니다. 지원팀에 로그를 보내기 전에 모든 민감한 정보(예: 현재 갱신 토큰 또는 액세스 토큰 필드)를 삭제하세요.

전체 HTTP 로깅을 사용하려면 다음 안내를 따르세요.

sync-cmd 또는 구성 관리자를 사용하여 GCDS가 실행되고 있지 않은지 확인합니다.
GCDS 설치 폴더로 이동합니다.
jre/lib/logging.properties 파일을 수정합니다.
파일 끝에 다음 행을 추가합니다.
java.util.logging.FileHandler.pattern = %h/gcdshttp%u.%g.log java.util.logging.FileHandler.limit = 5000000 java.util.logging.FileHandler.count = 100 java.util.logging.FileHandler.formatter = java.util.logging.SimpleFormatter handlers = java.util.logging.FileHandler com.google.api.client.http.level = CONFIG com.google.gdata.client.http.HttpGDataRequest.level = ALL sun.net.www.protocol.http.HttpURLConnection.level = ALL
파일을 저장합니다.
로그 기록을 추적으로 설정하여 GCDS 동기화를 다시 실행합니다.
homedir(Linux) 또는 프로필 폴더(Microsoft Windows)에 gcdshttp*.log라는 로그 파일이 생성됩니다. 이 파일은 용량이 클 수 있으므로 함께 보관처리하세요.
4단계에서 추가한 행을 삭제하여 이후에 대용량 로그 파일이 생성되지 않도록 합니다.

그런 다음 지원팀에 다음 파일을 제공하세요.

사용된 XML 파일
최신 동기화에서 생성된 추적 수준 로그
동기화로 생성된 gcdshttp*.log 파일

지원팀에서 이러한 로그를 사용하여 Directory API에서 GCDS에 제공한 정보와 GCDS의 대응 방식을 확인할 수 있습니다.

기록된 요청과 응답 내용은 각각 16KB의 크기로 제한됩니다. 로그 항목이 일부 잘려져 있다면 크기 제한을 초과한 것이므로, 아래에 권장된 대로 Fiddler를 사용하세요.

참고: Fiddler와 같은 디버깅 프록시를 GCDS와 함께 사용하려면 .vmoptions 파일을 업데이트하여 Windows에서 신뢰할 수 있는 인증서 저장소를 사용하도록 GCDS를 설정하고 CRL 확인을 사용 중지해야 합니다. 그런 다음 Fiddler를 GCDS에 프록시 서버로 설정(대개 포트 8888의 127.0.0.1)하면 Fiddler에서 연결을 기록합니다. Linux에서 GCDS를 사용하는 경우 Windows의 신뢰할 수 있는 인증서 저장소를 사용할 수 없으므로 Fiddler 루트 인증서를 GCDS의 Java 트러스트 저장소로 가져와야 합니다. 자세한 내용은 서버 인증서 가져오기를 참고하세요.

다른 시스템에 저장된 XML 파일을 열거나 다른 사용자로 XML 파일을 열려면 어떻게 해야 하나요?

다른 시스템에 저장된 XML 파일을 열거나 동일한 시스템에서 다른 사용자로 XML 파일을 여는 방법에 대한 안내는 구성 파일 사용하기를 참고하세요.

LDAP 디렉터리에서 데이터를 어떻게 내보낼 수 있나요?

GCDS 추적 수준 로그의 LDAP 데이터가 LDAP 서버에서 읽을 것으로 예상하는 데이터와 일치하지 않는 경우(예: 사용자를 찾을 수 없거나 속성의 값이 올바르지 않음) 데이터를 LDIF 형식으로 LDAP 디렉터리에서 내보내세요. 지원팀에서 해당 데이터를 GCDS 로그의 LDAP 데이터와 비교할 수 있습니다.

데이터를 내보낼 때 ldapsearch(Linux) 또는 ldifde(Windows)와 같은 LDAP 쿼리 도구를 사용하고 GCDS에서 실행되는 것과 동일한 조건을 시뮬레이션합니다.

GCDS에서 사용하도록 구성된 것과 동일한 연결 설정을 사용합니다.
GCDS를 실행하는 동일한 시스템에서 쿼리 도구를 실행합니다.
GCDS LDAP 인증에 동일한 사용자 이름을 사용합니다.

예

GCDS 로그에 사용자의 mail 속성이 표시되지 않으며 GCDS 검색 규칙 설정은 다음과 같습니다.

기본 DN: ou=Ireland,dc=altostrat,dc=com
범위: 하위 트리
검색 필터: (&(objectCategory=person)(objectClass=user))
서버: dc01.altostrat.com
포트: 636
프로토콜: LDAP+SSL
인증 사용자 DN: cn=GCDS,ou=Users,dc=altostrat,dc=com

다음 명령어를 사용합니다.

Linux: ldapsearch -v -b "ou=Ireland,dc=altostrat,dc=com" -s sub -h dc01.altostrat.com -p 636 -x -Z -D "cn=GCDS,ou=Users,dc=altostrat,dc=com" "(&(objectCategory=person)(objectClass=user))" mail givenname uniqueidentifier sn > out.ldif(시스템에 따라 명령을 수정해야 할 수 있습니다.)
Windows: ldifde -f out.ldif -s dc01.altostrat.com -v -t 636 -d "ou=Ireland,dc=altostrat,dc=com" -r "(&(objectCategory=person)(objectClass=user))" -p SubTree -l mail,givenname,uniqueidentifier,sn -a "cn=GCDS,ou=Users,dc=altostrat,dc=com" PASSWORD(PASSWORD 부분을 GCDS에서 설정한 LDAP 사용자의 비밀번호로 변경합니다.)

결과(out.ldif)에 영향을 받는 사용자의 mail 속성이 포함되지 않으면 LDAP 인프라에 문제가 있는 것입니다. LDAP에 액세스하는 데 사용하는 사용자의 권한과 관련이 있을 수 있습니다(예: OpenLDAP 및 Active Directory 모두에서 속성 수준 권한 설정을 허용함). 또는 3268이나 3269와 같은 글로벌 카탈로그 포트를 사용하는 경우 이 속성이 글로벌 카탈로그에 복제되지 않을 수 있습니다.

결과에 영향을 받는 사용자의 mail 속성이 포함되어 있으면 다음 세부정보를 Google Workspace 지원팀에 제공합니다.

out.ldif 파일
명령어를 실행한 명령 프롬프트 또는 터미널 창의 스크린샷
(먼저 비밀번호를 삭제해야 함)
GCDS trace 수준 로그

시뮬레이션 및 동기화

섹션 열기 | 모두 접고 상단으로 이동하기

시뮬레이션된 동기화를 실행하려면 알림 서버가 필요한가요?

시뮬레이션된 동기화를 실행하려면 메일을 보낼 수 있는 서버가 필요합니다. 메일 서버 시스템에서 GCDS를 실행하는 경우에는 메일 서버에 IP 주소 127.0.0.1을 사용할 수 있습니다. 혹은 메일 관리자에게 올바른 메일 정보를 문의하세요.

명령줄을 사용한 동기화가 GCDS에서 실행되지 않는 이유는 무엇인가요?

명령줄을 사용하여 동기화를 실행하는 경우 동기화가 시작되지 않으면 명령줄에서 -o 또는 --oneinstance 인수를 사용했는지 확인합니다.

이러한 인수 중 하나를 사용하는 경우 GCDS에서는 XML 구성 파일과 연결된 LOCK(.lock) 파일을 생성합니다. 이 때 동일한 서버에서 다른 LOCK 파일이 발견되면 GCDS에서는 여러 개의 GCDS 인스턴스가 동시에 실행되지 않도록 동기화를 실행하지 않습니다.

다른 GCDS 인스턴스가 실행되고 있지 않다면 서버에 다른 LOCK 파일이 있는지 확인합니다. 해당 파일을 수동으로 삭제하고 동기화를 다시 실행해 보세요.

동기화가 완료되지 않았습니다. API 문제일 수 있나요?

예를 들어 그룹의 전체 멤버십이 동기화되지 않는 등 동기화가 완료되지 않았다면 Directory API에 문제가 발생했을 수 있습니다. 문제가 GCDS 제품이 아닌 API와 관련된 것인지 확인하려면 Directory API를 직접 호출하고 결과를 검토하세요. API를 수동으로 호출하려면 다음 두 가지 옵션 중 하나를 선택합니다.

옵션 1: API 참조 페이지 사용하기

Admin SDK API 참조 개요로 이동합니다.
왼쪽에서 Directory API를 클릭한 다음 REST 리소스에 대해 쿼리하려는 REST 리소스로 이동합니다.
오른쪽에서 시도하려는 방법을 클릭하고 사용해 보기를 클릭합니다.
API 참조 페이지에 사용해 보기가 표시되지 않으면 옵션 2: OAuth 2.0 플레이그라운드 사용하기로 이동합니다.
GCDS를 승인하는 데 사용한 관리자 인증 정보를 입력합니다.
자세한 내용은 Google 도메인 설정 정의하기를 참고하세요.
정보를 검토하여 API 응답이 예상대로 인지 확인합니다.

옵션 2: OAuth 2.0 플레이그라운드 사용하기

OAuth 2.0 플레이그라운드를 엽니다.
다음 옵션 중 하나를 선택합니다.
- 목록에서 범위를 선택합니다.
- API 참조 페이지의 승인 범위 목록에서 범위를 복사합니다. 그런 다음 내 범위 입력 필드에 범위를 붙여넣습니다.
API 승인을 클릭합니다.
GCDS를 승인하는 데 사용한 관리자 인증 정보를 입력합니다.
자세한 내용은 Google 도메인 설정 정의하기를 참고하세요.
토큰의 승인 코드 교환을 클릭합니다.
프로세스가 성공하면 3단계: API 요청 구성하기로 리디렉션됩니다.
요청된 정보를 완료합니다.
도움말: API 메서드 참조 웹페이지에서 대부분의 정보를 찾을 수 있습니다.
요청 보내기를 클릭합니다.
정보를 검토하여 API 응답이 예상대로 인지 확인합니다.

오류

섹션 열기 | 모두 접고 상단으로 이동하기

EntityDoesNotExist/EntityExists 오류 또는 충돌이 발생하는 이유는 무엇인가요?

XML 구성 파일에서 useDynamicMaxCacheLifetime 옵션을 설정합니다. 이 옵션은 최대 8일 동안 데이터를 캐시하고 중소 규모의 데이터 세트로 캐시를 더 자주 비워 캐시된 데이터가 오래되거나 새 데이터와 충돌하지 않도록 GCDS를 구성합니다. GCDS 3.2.1 이상으로 생성된 구성에서는 useDynamicMaxCacheLifetime 옵션이 자동으로 사용 설정됩니다.

참고: 이러한 오류는 일반적으로 Google 도메인에서 직접 수정하는 경우에 발생합니다. GCDS를 사용하여 동기화하는 경우 Google 도메인을 직접 변경하는 대신 LDAP 디렉토리에서 사용자, 그룹, 기타 항목을 변경해야 합니다. 그런 다음 GCDS를 사용하여 Google 도메인에 변경사항을 동기화합니다.

메모리 관련 오류를 수정하려면 어떻게 해야 하나요?

메모리 관련 오류가 표시되면 자바 가상 머신의 힙 크기를 늘려야 합니다. GCDS의 설치 디렉터리에서 sync-cmd.vmoptions 및 config-manager.vmoptions 파일을 수정하여 힙 크기를 늘립니다. 관련 항목은 다음과 같이 표시됩니다.

-Xmx1000m(힙 크기에 대한 최대 메모리 할당량)
-Xms64m(힙 크기에 대한 최소 메모리양)

sync-cmd 및 구성 관리자 버전에 모두 변경사항이 적용되도록 sync-cmd.vmoptions 및 config-manager.vmoptions 파일을 모두 수정합니다.

메모리양을 늘리려면 -Xmx 수를 수정합니다. 숫자 다음에 표시되는 'm'은 메모리가 메가바이트(MB)로 측정됨을 나타냅니다. 올바른 메모리 양은 GCDS 서버의 메모리의 양과 동기화하는 데 필요한 메모리 양에 따라 다릅니다. 올바르게 크기를 설정하려면 숫자를 여러 번 변경해야 할 수 있습니다. GCDS를 실행하는 데 필요한 RAM 여유 공간에 대한 자세한 내용은 GCDS 시스템 요구사항을 참고하세요.

캐시 사용을 중지하면 GCDS에서 오류가 계속 발생하는 이유는 무엇인가요?

제외 규칙 구성 오류와 같은 구성 문제로 인해 문제가 발생할 수 있습니다. 이러한 유형의 구성 오류는 GCDS 캐싱으로 숨길 수 있습니다.

GCDS는 Google 서비스(예: Google Workspace 또는 Cloud ID) 데이터를 최대 8일 동안 캐시합니다. GCDS에서는 캐시된 데이터의 크기에 따라 캐시를 더 자주 삭제할 수 있습니다. 하지만 캐시가 삭제되지 않으면 최대 8일 동안 업데이트를 확인하지 못할 수도 있습니다.

예를 들어 LDAP 데이터를 동기화하고 Google 서비스(예:Google Workspace 또는 Cloud ID)의 새 그룹을 만듭니다. 그런 다음 제외 규칙을 만들면 이후 동기화에서 그룹을 제외할 수 있습니다. 이 제외 규칙에 구성 오류가 있어 실패하게 됩니다. 하지만 이후 캐시된 데이터가 동기화되면 그룹은 Google 서비스에 유지됩니다. 캐시를 삭제하면서 다시 동기화하면 구성 오류로 Google 서비스에서 그룹이 삭제됩니다.

캐시를 수동으로 삭제하려면 다음 안내를 따르세요.

구성 관리자에서 동기화를 실행하고 동기화를 수행할 때 캐시를 삭제하는 옵션을 선택합니다.
명령어에서 동기화를 실행하고 -f 인수를 사용하여 캐시를 강제 삭제합니다.
XML 구성 파일을 수정하여 maxCacheLifetime 값을 0으로 설정합니다.

중요: 캐시를 강제 삭제하면 동기화 시간이 급격히 증가할 수 있습니다.

사용자 및 그룹

섹션 열기 | 모두 접고 상단으로 이동하기

GCDS에서 이미 존재하는 Google 사용자를 만들려고 하는 이유는 무엇인가요?

409: 항목이 이미 존재합니다라는 오류가 표시되면 GCDS에서 이미 존재하는 Google 사용자를 만들려고 시도하는 중입니다. 이후의 동기화에서 오류가 표시되지 않는 경우 GCDS 캐시가 오래되었을 수 있으므로 오류를 무시해도 됩니다.

동기화할 때마다 또는 며칠에 한 번씩 문제가 발생하는 경우 가장 가능성이 높은 원인은 다음과 같습니다.

Google 사용자 제외 규칙이 너무 광범위하여 LDAP 디렉터리에도 있는 일부 Google 사용자와 일치합니다.
쿼리 범위가 너무 좁아서 쿼리가 LDAP 디렉터리에도 있는 일부 Google 사용자와 일치하지 않습니다.

두 경우 모두 GCDS에서 이미 존재하는 Google 사용자를 무시할 수 있습니다. 이러한 사용자가 LDAP 사용자 검색 규칙 결과에 있는 경우 GCDS에서는 Google 계정에 해당 사용자를 만들려고 합니다.

이 문제를 해결하려면 제외 규칙 또는 검색어를 조정하세요. 또는 GCDS에서 LDAP 디렉터리의 사용자를 완전히 무시하도록 하려면 LDAP 사용자 검색 규칙을 조정하거나 LDAP 사용자 제외 규칙을 만드세요. 자세한 내용은 제외 규칙 및 쿼리로 데이터 제외하기를 참고하세요.

일부 사용자가 그룹 회원으로 동기화되지 않는 이유는 무엇인가요?

그룹 회원을 모든 사용자 검색 규칙의 결과와 별도로 동기화하기 위해 GCDS에서는 기본적으로 INDEPENDENT_GROUP_SYNC 옵션을 사용 설정합니다. 그룹 동기화에 회원 참조 속성을 사용 중인 경우 GCDS에서는 사용자 검색 규칙과 관계없이 LDAP 디렉토리에 있는 모든 사용자의 이메일 주소를 확인하려고 합니다.

사용자 검색 규칙의 결과만을 기준으로 그룹 회원을 동기화하려면 구성 XML 파일에서 INDEPENDENT_GROUP_SYNC를 삭제합니다. 그러면 GCDS에서는 다음을 수행합니다.

사용자 검색 규칙의 결과를 사용하여 그룹 멤버십 해결
사용자 동기화에 포함된 사용자만 그룹 회원으로 동기화
일반 설정에서 사용자 계정 동기화를 사용 중지한 경우에도 사용자 검색 규칙 실행
하지만 자격 요건을 갖춘 사용자가 그룹 회원 자격도 갖춘 경우라면 결과는 Google에서 사용자가 아닌 그룹 회원으로 동기화됩니다.

일반적으로 이것이 바람직한 동기화 방식은 아니며, 특히 공유 연락처를 동기화하고 있거나 연락처에 있는 그룹 회원인 경우에는 더욱 그렇습니다. 이 경우 연락처는 그룹 회원으로 동기화되지 않습니다.

동기화할 때마다 일부 사용자 또는 그룹이 다시 생성되는 이유는 무엇인가요?

이 문제는 그룹 이름 속성으로 구성된 LDAP 속성에 전체 이메일 주소가 포함되지 않은 경우 발생합니다. 문제를 해결하려면 그룹 검색 규칙을 검사하여 GCDS에서 그룹 이름에 전체 이메일 주소를 사용하는지 확인합니다. 다음 방법 중 하나를 사용하세요.

그룹 이름 속성을 메일과 같이 각 그룹의 전체 이메일 주소를 지정하는 다른 LDAP 속성으로 설정합니다.
Google 도메인 설정에 LDAP 이메일 주소에서 도메인 이름 대체를 사용 설정하여 그룹 이름 속성이 Google 측 그룹 이름과 일치하도록 합니다.
그룹 검색 규칙에 그룹 이름 접미사를 지정하여 그룹 이름에 도메인 이름을 추가합니다.

Active Directory에 회원 수가 1,500명 이상인 그룹은 제대로 동기화되지 않습니다.

LDAP 구성 섹션의 서버 유형 입력란에 MS Active Directory가 선택되었는지 확인합니다.

'LDAP 이메일 주소에서 도메인 이름 대체'를 사용하려면 어떻게 해야 하나요?

이 옵션(XML 파일에 SUPPRESS_DOMAIN으로 표시됨)은 LDAP 디렉터리의 이메일 주소가 Google 도메인이 아닌 다른 도메인에 있는 경우에 사용됩니다. 이 옵션을 사용 설정하면 GCDS는 읽는 모든 이메일 주소에서 도메인 부분을 없앱니다.

모든 처리가 도메인 이름 없이 수행됩니다. 이메일 주소를 기반으로 한 제외 규칙을 사용하는 경우 제외 규칙에서 이메일 주소의 로컬 부분만 고려하면 됩니다.

예를 들어 LDAP 이메일 주소에서 도메인 이름 대체를 사용 중지하고 일치검색 제외 규칙을 만드는 경우 일치시킬 사용자의 이메일 주소로 luka@example.com을 입력합니다. LDAP 이메일 주소에서 도메인 이름 대체를 사용 설정한 경우 luka를 사용합니다. @example.com이 비교 전에 삭제되므로 luka@example.com과의 일치 시도는 작동하지 않습니다.

정적 그룹과 동적 그룹을 중첩할 수 있나요?

GCDS를 사용하여 그룹을 프로비저닝하면 동적 그룹을 정적 그룹 아래(또는 정적 그룹을 동적 그룹 아래)에 중첩할 수 없습니다. GCDS에서는 정적 그룹을 동적 그룹과 별도로 쿼리해야 하지만 모든 중첩 그룹이 동일한 쿼리의 일부여야 합니다.

정기적으로 모든 동적 그룹을 쿼리하는 작업을 자동화하는 방법과 같이 동적 그룹을 정적 그룹으로 구현하는 방법을 찾아보세요. 그러면 GCDS에서 동적 그룹을 프로비저닝하지 않고 동적 그룹에서 생성된 정적 그룹을 프로비저닝에 사용할 수 있습니다.

내 LDAP 쿼리에서 예상치 못한 결과가 나타나는 이유는 무엇인가요?

LDAP 쿼리의 결과는 구성 관리자 설정 및 LDAP 서버에 따라 다릅니다. LDAP 검색 규칙에서 예상치 못한 결과가 반환되는 경우 다음 문제 해결 도움말을 참고하세요. 다음을 확인하세요.

구성 관리자에 LDAP 쿼리가 올바르게 설정됨: 검색 규칙을 설정할 때 LDAP 쿼리 테스트를 클릭하여 확인합니다. 자세한 내용은 LDAP 검색 규칙을 사용하여 데이터 동기화하기를 참고하세요.
여러 쿼리가 서로 충돌하지 않음: 쿼리 결과를 변경하는 검색 또는 제외 규칙을 설정하지 않았는지 확인합니다.
LDAP 서버의 승인된 사용자에게 충분한 권한이 있음: LDAP 서버를 인증하는 데 사용되는 관리자가 동일한 서버에서 명령줄을 사용할 수 있는지 확인합니다. LDAP 서버에서 쿼리를 시도해 보고 결과를 확인합니다.

그룹을 만들 수 없음 오류

그룹 ... 을 만들 수 없습니다라는 오류 메시지가 표시될 수 있습니다. 메시지: GCDS 로그에서 이 리소스/API에 액세스하도록 승인되지 않았습니다.

문제를 해결하려면 사용자 및 그룹 이메일 주소의 도메인이 포함된 Active Directory(AD) 속성이 최고 관리자 계정에서 사용하는 도메인과 일치하는지 확인하세요.