NetJoinDomain 함수(lmjoin.h)
NetJoinDomain 함수는 컴퓨터를 작업 그룹 또는 도메인에 조인합니다.
구문
NET_API_STATUS NET_API_FUNCTION NetJoinDomain(
[in] LPCWSTR lpServer,
[in] LPCWSTR lpDomain,
[in] LPCWSTR lpMachineAccountOU,
[in] LPCWSTR lpAccount,
[in] LPCWSTR lpPassword,
[in] DWORD fJoinOptions
);
매개 변수
[in] lpServer
도메인 조인 작업을 실행할 컴퓨터의 DNS 또는 NetBIOS 이름을 지정하는 상수 문자열에 대한 포인터입니다. 이 매개 변수가 NULL이면 로컬 컴퓨터가 사용됩니다.
[in] lpDomain
조인할 도메인 또는 작업 그룹의 이름을 지정하는 null로 끝나는 상수 문자열에 대한 포인터입니다.
필요에 따라 조인 작업을 수행할 기본 도메인 컨트롤러를 지정할 수 있습니다. 이 instance 문자열은 DomainName\MachineName 형식이어야 합니다. 여기서 DomainName은 조인할 도메인의 이름이고 MachineName은 조인을 수행할 도메인 컨트롤러의 이름입니다.
[in] lpMachineAccountOU
필요에 따라 컴퓨터 계정에 대한 OU(조직 구성 단위)의 RFC 1779 형식 이름을 포함하는 null로 끝나는 상수 문자열에 대한 포인터를 지정합니다. 이 매개 변수를 지정하는 경우 문자열에는 전체 경로(예: OU=testOU,DC=domain,DC=Domain,DC=com)가 포함되어야 합니다. 그렇지 않으면 이 매개 변수는 NULL이어야 합니다.
[in] lpAccount
도메인 컨트롤러에 연결할 때 사용할 계정 이름을 지정하는 null로 끝나는 상수 문자열에 대한 포인터입니다. 문자열은 인터넷 스타일 로그인 이름(예: "someone@example.com") 형식으로 사용자의 도메인 NetBIOS 이름 및 사용자 계정(예: REDMOND\user) 또는 UPN(사용자 계정 이름)을 지정해야 합니다. 이 매개 변수가 NULL이면 호출자의 컨텍스트가 사용됩니다.
[in] lpPassword
lpAccount 매개 변수가 계정 이름을 지정하는 경우 이 매개 변수는 도메인 컨트롤러에 연결할 때 사용할 암호를 가리킵니다. 그렇지 않으면 이 매개 변수는 NULL이어야 합니다.
보안되지 않은 조인에 대한 사용자 암호가 아닌 로컬 컴퓨터 계정 암호를 지정할 수 있습니다. 자세한 내용은 fJoinOptions 매개 변수에 설명된 NETSETUP_MACHINE_PWD_PASSED 플래그에 대한 설명을 참조하세요.
[in] fJoinOptions
조인 옵션을 정의하는 비트 플래그 집합입니다. 이 매개 변수는 Lmjoin.h 헤더 파일에 정의된 다음 값 중 하나 이상일 수 있습니다.
| 값 | 의미 |
|---|---|
|
컴퓨터를 도메인에 조인합니다. 이 값을 지정하지 않으면 컴퓨터를 작업 그룹에 조인합니다. |
|
도메인에 계정을 만듭니다. |
|
조인 작업이 업그레이드의 일부로 발생합니다. |
|
컴퓨터가 이미 도메인에 가입되어 있더라도 새 도메인에 조인할 수 있습니다. |
|
보안되지 않은 가입을 수행합니다.
이 옵션은 도메인 사용자 자격 증명을 사용하여 인증하지 않고 미리 만들어진 계정에 도메인 가입을 요청합니다. 이 옵션은 NETSETUP_MACHINE_PWD_PASSED 옵션과 함께 사용할 수 있습니다. 이 경우 lpPassword 는 미리 만들어진 컴퓨터 계정의 암호입니다. WINDOWS Vista SP1 및 Windows Server 2008 이전에는 안전하지 않은 조인이 도메인 컨트롤러에 인증되지 않았습니다. 모든 통신은 null(인증되지 않은) 세션을 사용하여 수행되었습니다. WINDOWS Vista SP1 및 Windows Server 2008부터 컴퓨터 계정 이름 및 암호는 도메인 컨트롤러에 인증하는 데 사용됩니다. |
|
lpPassword 매개 변수가 사용자 암호가 아닌 로컬 컴퓨터 계정 암호를 지정했음을 나타냅니다. 이 플래그는 보안되지 않은 조인에만 유효하며, NETSETUP_JOIN_UNSECURE 플래그를 설정하여 표시해야 합니다.
이 플래그를 설정하면 조인 작업이 성공한 후 해당 값이 유효한 컴퓨터 암호인 경우 컴퓨터 암호가 lpPassword 값으로 설정됩니다. |
|
현재 컴퓨터 개체의 SPN(서비스 사용자 이름) 및 DnsHostName 속성을 업데이트해서는 안 됨을 나타냅니다.
일반적으로 이러한 속성은 조인 작업 중에 업데이트됩니다. 대신 NetRenameMachineInDomain 함수에 대한 후속 호출 중에 이러한 속성을 업데이트해야 합니다. 이러한 속성은 이름 바꾸기 작업 중에 항상 업데이트됩니다. 자세한 내용은 아래 설명 부분을 참조하십시오. |
|
기존 계정이 도메인 컨트롤러인 경우 도메인 가입을 허용합니다.
참고 이 플래그는 Windows Vista 이상에서 지원됩니다.
|
|
lpServer 매개 변수에 지정된 대상 컴퓨터를 lpServer 매개 변수에 지정된 컴퓨터의 레지스트리에서 쿼리된 새 이름으로 조인합니다.
이 옵션은 컴퓨터를 다시 부팅하기 전에 SetComputerNameEx 가 호출된 경우에 사용됩니다. 새 컴퓨터 이름은 다시 부팅될 때까지 적용되지 않습니다. 이 옵션을 사용하면 호출자가 도메인 조인 작업 중에 새 이름을 사용하도록 NetJoinDomain 함수에 지시합니다. NetJoinDomain을 성공적으로 호출한 후 다시 부팅해야 합니다. 이때 컴퓨터 이름 변경 및 도메인 멤버 자격 변경이 모두 영향을 미칩니다. 참고 이 플래그는 Windows Vista 이상에서 지원됩니다.
|
|
쓰기 가능한 도메인 컨트롤러 없이 미리 만들어진 계정을 사용하여 lpServer 매개 변수에 지정된 대상 머신을 조인합니다.
이 옵션은 계정이 이미 프로비전되어 읽기 전용 도메인 컨트롤러에 복제된 경우 컴퓨터를 도메인에 조인하는 기능을 제공합니다. 대상 읽기 전용 도메인 컨트롤러는 '\' 문자로 구분된 도메인 이름 뒤에 lpDomain 매개 변수의 일부로 지정됩니다. 이 프로비저닝에는 컴퓨터 암호가 포함되어야 합니다. 컴퓨터 계정은 그룹 멤버 자격을 통해 암호 복제 정책에 허용되는 목록에 추가되어야 하며, 계정 암호는 조인 작업 전에 읽기 전용 도메인 컨트롤러에 복제되어야 합니다. 자세한 내용은 암호 복제 정책 관리에 대한 정보를 참조하세요. Windows 7부터는 오프라인 도메인 조인 메커니즘을 사용하는 것이 대체 메커니즘입니다. 자세한 내용은 NetProvisionComputerAccount 및 NetRequestOfflineDomainJoin 함수를 참조하세요. 참고 이 플래그는 Windows Vista 이상에서 지원됩니다.
|
|
도메인에 가입할 때 레지스트리에서 기본 설정 도메인 컨트롤러를 설정하려고 하지 않습니다.
참고 이 플래그는 Windows 7, Windows Server 2008 R2 이상에서 지원됩니다.
|
|
도메인에 가입할 때 Netlogon 캐시를 만들지 않습니다.
참고 이 플래그는 Windows 7, Windows Server 2008 R2 이상에서 지원됩니다.
|
|
도메인에 가입할 때 Netlogon 서비스가 강제로 시작되지 않습니다.
참고 이 플래그는 Windows 7, Windows Server 2008 R2 이상에서 지원됩니다.
|
|
오프라인 조인에 대해서만 도메인을 조인하는 경우 대상 컴퓨터 호스트 이름 및 NetBIOS 이름을 설정합니다.
참고 이 플래그는 Windows 7, Windows Server 2008 R2 이상에서 지원됩니다.
|
|
도메인에 가입할 때 도메인 조인 중에 다른 설정을 재정의하고 SPN(서비스 사용자 이름)을 설정합니다.
참고 이 플래그는 Windows 7, Windows Server 2008 R2 이상에서 지원됩니다.
|
|
도메인에 가입할 때 기존 계정을 다시 사용하지 마세요.
참고 이 플래그는 Windows 7, Windows Server 2008 R2 이상에서 지원됩니다.
|
|
이 비트를 설정하면 NetJoinDomain 함수에서 인식할 수 없는 플래그가 무시되고 NetJoinDomain 은 플래그가 설정되지 않은 것처럼 동작합니다. |
반환 값
함수가 성공하면 반환 값이 NERR_Success.
함수가 실패하면 반환 값은 다음 오류 코드 또는 시스템 오류 코드 중 하나일 수 있습니다.
| 반환 코드 | 설명 |
|---|---|
|
액세스가 거부되었습니다. 이 오류는 호출자가 대상 컴퓨터의 Administrators 로컬 그룹의 구성원이 아닌 경우 반환됩니다. |
|
매개 변수가 잘못되었습니다. lpDomain 매개 변수가 NULL이면 이 오류가 반환됩니다. |
|
지정한 도메인이 없습니다. |
|
요청이 지원되지 않습니다. 이 오류는 lpServer 매개 변수에 지정된 컴퓨터가 fJoinOptions 매개 변수에 전달된 일부 옵션을 지원하지 않는 경우 반환됩니다. |
|
지정된 작업 그룹 이름이 잘못되었습니다. |
|
컴퓨터가 이미 도메인에 가입되어 있습니다. |
|
워크스테이션 서비스가 시작되지 않았습니다. |
|
이 스레드에 대한 원격 프로시저 호출이 이미 진행 중입니다. |
|
원격 프로시저 호출 프로토콜 시퀀스는 지원되지 않습니다. |
설명
도메인 또는 작업 그룹에 컴퓨터를 조인(및 연결 해제)하는 작업은 대상 컴퓨터의 Administrators 로컬 그룹 구성원만 수행할 수 있습니다. 도메인 관리자는 위임 및 권한 할당을 사용하여 도메인에 가입하기 위한 추가 요구 사항을 설정할 수 있습니다.
NetJoinDomain 함수를 원격으로 호출하는 경우 이러한 상황에서 자격 증명을 위임할 수 없으므로 자격 증명을 제공해야 합니다.
다른 프로세스 또는 동일한 프로세스의 다른 스레드는 NetJoinDomain 함수를 동시에 호출해서는 안 됩니다. 이 경우 컴퓨터가 일관되지 않은 상태로 남을 수 있습니다.
조인 작업 중에 문제가 발생하는 경우 컴퓨터 계정을 삭제하지 않아야 하며 다른 조인 시도를 통해 즉시 삭제를 수행하면 안 됩니다. 이로 인해 조사하기 어려운 복제 관련 문제가 발생할 수 있습니다. 컴퓨터 계정을 삭제할 때 다른 조인 작업을 시도하기 전에 변경 내용이 모든 도메인 컨트롤러에 복제될 때까지 기다립니다.
작업을 완료하려면 NetJoinDomain 함수를 호출한 후 시스템을 다시 부팅해야 합니다.
Windows Server 2003 및 Windows XP: NetJoinDomain 함수를 호출하기 전에 NetRenameMachineInDomain 함수를 호출하는 경우 이름 바꾸기 작업이 수행될 때까지 컴퓨터 개체에서 SPN 및 DnsHostName 속성의 업데이트를 연기해야 합니다. 특정 상황에서 조인 작업이 실패할 수 있기 때문입니다. 이러한 상황의 예로 현재 컴퓨터 이름에서 파생된 SPN이 컴퓨터가 조인하는 새 도메인에서 유효하지 않지만 이름 바꾸기 작업 후에 컴퓨터에서 사용할 새 이름에서 파생된 SPN이 새 도메인에서 유효한 경우입니다. 이 경우 NetJoinDomain 을 호출할 때 fJoinOptions 매개 변수에 NETSETUP_DEFER_SPN_SET 플래그를 지정하여 이름 바꾸기 작업까지 두 속성의 업데이트를 연기하지 않으면 NetJoinDomain에 대한 호출이 실패합니다.
요구 사항
| 지원되는 최소 클라이언트 | Windows 2000 Professional[데스크톱 앱만] |
| 지원되는 최소 서버 | Windows 2000 Server[데스크톱 앱만] |
| 대상 플랫폼 | Windows |
| 헤더 | lmjoin.h(Lm.h 포함) |
| 라이브러리 | Netapi32.lib |
| DLL | Netapi32.dll |
참고 항목
NetRemoveAlternateComputerName