Demystifying clientsettings.ini

21 08 2010

Managing Windows CE based embedded devices via System Center Configuration Manager (SCCM, formerly known as SMS Server) is not as straightforward as managing WES 2009 or WES 7 devices. This is due to the fact that the client for CE devices is different from the advanced client that can be used for desktop systems and WES devices as well.
The differences start with the setup, which is not just clicking a cab file to install the client. A special configuration file called clientsettings.ini needs to be configured correctly. This is essential because misconfigured installations will not be able to connect to the backend SCCM server.
The challenge in this case is to understand correctly what the different settings target individually.
The configuration begins looking at the mode the SCCM server runs. This can be mixed mode or native mode. Native mode is much more secure because it uses certificates for authentication and encryption, while mixed mode most commonly is used in Intranet scenarios where security is provided by other means.

A  typical ini file for a native mode installation looks like this:

[Settings]
; **** Certificate Enrollment Settings ****

; CertEnrollServer is the name of the Internet Information Server (IIS)
; web server front end to the certificate authority (CA).
CertEnrollServer=SCCM.Wechsler-Consulting.de

; *****************************************
; **** OPTIONAL CONFIGURABLE SETTINGS *****

; CertEnrollServerPort is the Port number of the Internet Information Server (IIS)
; web server front end to the certificate authority (CA).
CertEnrollServerPort=80

; CertRequestPage is the web page on web server that receives
; the certificate request.
CertRequestPage=/certsrv/certfnsh.asp

; CertDownloadPage is the web page on the web server used for
; downloading the certificate.
CertDownloadPage =/certsrv/certnew.cer

; CertChainDownloadPage is the web page on the web server used for
; downloading the certificate chain.
CertChainDownloadPage=/certsrv/certnew.p7b

; DMServerName is the server name of the Device Management
; Point which the device will connect to. 
; Note this may be set via a command line to the dmcommoninstaller,
; and if this is used it will override the value specified in
; this file
; ** This must be changed for correct DM client operation **
DMServerName=SCCM.Wechsler-Consulting.de

; Client Install Action:
; Set to ‘None’ to perform no change in DM client state
; Set to ‘Install’ to install the DM client
; Set to ‘Uninstall’ to remove the DM client
ClientInstallAction=Install

; Client Install Type option:
; Set to ‘Clean’ to remove program database
; Set to ‘Preserve’ to keep the record of installed programs
InstallType=Clean

; Secure Mode option:
; The default value here is None.
; Set to ‘None’ which means no Server and Client Authentication is required
; Set to ‘SSLServerAuth’ which means HTTPS (or secure HTTP) server authentication is required.
; A server certificate will have to be installed on the device, see documentation for more information
; Set to ‘NativeMode’ which means HTTPS (or secure HTTP) mutual authentication is required between Device Client
; and the DMP/DP.
; This mode is also called Native Mode. A client Auth Certificate is required for registering the client with SMS database
; and signing the client data.
SecurityMode=NativeMode

; Create Connection option:
; Set to ‘ALL’ to allow agent to invoke a connection for any action
; Set to ‘USER’ to allow agent to invoke a connection only for a user invoked action
; Set to ‘NEVER’ to prevent agent invoking connections for any operations
CreateConnection=ALL

; Enforce Configuration option:
; This option permits the device configuration UI to be disabled for certain options so that the user may not change them
; Set to ‘None’ to allow the user to change server name, https and auto connect options
; Note that server name and https flag will be overwritten when the DM installer runs, for example whenever the device is docked.
; Set to ‘ServerName’ to disable user edit of the server name and https options
; Set to ‘All’ to disable user edit of the server name, https and auto connect options
EnforceConfig=None

; Import certificates option:
; This setting imports the certificate files (*.cer) to the certificate store on the device.
; This option is not required set up mutual authentication between the client and Device Management Point.
; Be sure to include certificate files (*.cer) in the same directory as DmCommonInstaller.exe
; Set to ‘True’ to import certificates
; Set to ‘False’ to not import certificates
ImportCerts=True

; Certificate Enrollment action:
; Set to ‘None’ to not enroll a certificate
; Set to ‘Enroll’ to enroll a client authentication certificate and add server certificate to the device’s ROOT certificate store,
; if the existing certificate cannot be used for device registration.
; The user will be prompted for their credentials to enroll the certificate
; Set to ‘ForceEnroll’ to enroll a client authentication certificate and add server certificate to the device’s ROOT certificate store
; irrespective of the current state of the existing enrolled certificate.
; The user will be prompted for their credentials to enroll the certificate
CertEnrollAction=ForceEnroll

; SMS Site Code option:
; This value is the three letter SMS site code for the site the device client will be installed into
; This is required for Native Security Mode only. See documentation for more information.
; ** This must be changed for correct DM client operation in Native Security Mode **
SiteCode=WEC

; Enable SMS Site Server Signing Certificate auto renewal option:
; This value controls whether the device client will automatically renew the Site Server Signing Certificate when in Native Secure Mode, see
; documentation for more information
; The default value is False
; Set to ‘True’ to enable SMS Site Server Signing Certificate auto renewal
; Set to ‘False’ to disable SMS Site Server Signing Certificate auto renewal
EnableSSSCRenewal=True

; Internet Connection option:
; This value indicates whether the device client is connecting to the DMP from the internet
; The default value is False
; Set to ‘True’ if the device client is connecting to the DMP from the internet
; Set to ‘False’ if the device client is not connecting to the DMP from the internet
InternetConnected=True

; Enrolled Certificate Renewal options:
; The number of days prior to the expiry of the existing valid certificate that the certificate will be renewed.
; Set to ‘None’ – default is 7 days
EnrolledCertRenewPeriod=7

; Subject Name of the Certificates the DM Client uses to register the Device.
; DM Client tries all the certificates that match this Subject Name criteria (it is a substrign match)
; None maps to empty string
CertSubjectName=Administrator

; FSPServerName is the server name of the Fallback Status
; Point which the device will connect to send FSP Messages. 
; ** This must be changed for correct DM client operation **
FSPServerName=SCCM.Wechsler-Consulting.de

; FSP Port is the primary http port the DM Client communicates to the FSP Server
FSPPort=443

; FSP Alternate Port is the alternate http port the DM Client communicates to the FSP Server
; if it fails to communicate over the primary port
FSPAlternatePort=80

; ****  END MAIN CONFIGURABLE SETTINGS ****

; *****************************************
; **** OPTIONAL CONFIGURABLE SETTINGS *****
; Uncomment these settings to enable them

; Server Port – changes the http/https port the DM client communicates
; to the DMP server
;ServerPort=443

; Pre install command line – this will be run prior to install
; of the DM client agent and other actions
;Pre-InstallCommandLine = \Temp\DmInstall\pre-test.exe

; Post install command line – this will be run after the install
; of the DM client agent and other actions
;Post-InstallCommandLine = \Temp\DmInstall\post-test.exe

; Additional Files – these will be copied to the \temp\dminstall folder on the device.
; Ensure a unique entry for each file by appending a number to the ‘AdditionalFile’ name
; All files in the \temp\dminstall folder will be deleted at the conclusion of setup.
;AdditionalFile0 = pre-test.exe
;AdditionalFile1 = post-test.exe
;AdditionalFile2 = test.dat
; **** END OPTIONAL CONFIGURABLE SETTINGS *****

; *************************************
; Client – Specifies the Device client cab file
; Use DeviceClient_ce4.2_arm.CAB for PPC03 platform
; Use DeviceClient_ce5.0_arm.CAB for PPC05 and PPC06 platform
; Use DeviceClient_SP_CE4.2_ARM.CAB for SP03 platform
; Use DeviceClient_SP_CE5.0_ARM.CAB for SP05 and SP06 platform
; Use DeviceClient_WINCE5.0_ARM.CAB for WIN CE ARM platform
; Use DeviceClient_WINCE5.0_X86.CAB for WIN CE x86 platform
Client = deviceclient_wince6.0_arm.CAB
ClientVersion = 4.00.6487.2121
; enable verbose logging ; true or false
EnableVerboseLogging=true

This is quite an overwhelming amount of data and its configuration requires detailed understanding of SCCM.
So let’s shed some light on this.

These entries have effect on or describe the enrollment of a client device at a Microsoft Certificate server to obtain a client certificate for authentication.

[Settings]

CertEnrollServer=SCCM.Wechsler-Consulting.de
CertEnrollServerPort=80
CertRequestPage=/certsrv/certfnsh.asp
CertDownloadPage =/certsrv/certnew.cer
CertChainDownloadPage=/certsrv/certnew.p7b

EnrolledCertRenewPeriod=7
CertSubjectName=Administrator
CertEnrollAction=ForceEnroll

If one has a different certificate server than the Microsoft one, this needs to be adjusted to fit the requirements, which might not be straightforward. The CE client always acquires a user certificate, not a machine certificate, but this cert must support the client authentication certificate option.
CertSubjectName is the name under which the user certificate is acquired from the certificate server and EnrollmentCertRenewPerod tells the client to renew the client certificate 7 days before expiration.

The next settings are important for the overall installation:
DMServerName=SCCM.Wechsler-Consulting.de
is the FQDN pointing to the device management point of SCCM. If this is wrong nothing ever will work.
ClientInstallAction=Install
This is an important setting which is used to install, un-install or update the client. Use solely clientsettings.ini to control the installation. All other ways e.g. uninstall via Control Panel –> Programs are not working correctly!
InstallType=Clean
Clean install – always is my recommendation 😉 
SecurityMode=NativeMode
the mode the SCCM server is in
CreateConnection=ALL
recommended for most robust operation, can be fine tuned for higher security
EnforceConfig=None
If set to true users are not able to change client settings.
ImportCerts=True
In native mode certificates for site authentication, code signing and web server communication need to be installed. They must be provided as .cer files in the same directory a the client setup. This settings automatically imports the certificates into the client certificate store. To get more information about this there is a good tutorial on a site called netsaber.
SiteCode=WEC
The site code of the SCCM server
EnableSSSCRenewal=True
Controls the renewal of SCCM certificates
InternetConnected=True
Must be true, if clients connect from the Internet

The next section is for the fallback status point, a SCCM role that allows clients that cannot connect into SCCM to generate error reports, which help troubleshooting this errors:
FSPServerName=SCCM.Wechsler-Consulting.de
FSPPort=443
FSPAlternatePort=80
Client Version is also quite important. If this setting is incorrect setup will install completely but the rollback the installation. Therefore be sure to get this right! By the way. the setup log is quite confusing in this case.
ClientVersion = 4.00.6487.2121

Logging set to verbose should be false in a production environment to preserve client resources.
EnableVerboseLogging=true

Mixed Mode

The clientsettings.ini for mixed mode looks pretty similar, but the certificate stuff can be neglected as soon as You set the security mode to Mixed Mode (the setting is “None”). An .ini fo this mode could look like this:

[Settings]

CertEnrollServer=SCCM.Wechsler-Consulting.de
CertEnrollServerPort=80
CertRequestPage=/certsrv/certfnsh.asp
CertDownloadPage =/certsrv/certnew.cer
CertChainDownloadPage=/certsrv/certnew.p7b
EnrolledCertRenewPeriod=7
CertSubjectName=Administrator
CertEnrollAction=None

DMServerName=SCCM.Wechsler-Consulting.de
ClientInstallAction=Install
InstallType=Clean
SecurityMode=None 
CreateConnection=ALL
EnforceConfig=None
ImportCerts=False
SiteCode=WEC
EnableSSSCRenewal=False
InternetConnected=False
FSPServerName=SCCM.Wechsler-Consulting.de
FSPPort=443
FSPAlternatePort=80
ClientVersion = 4.00.6487.2121
EnableVerboseLogging=True

A successful installation can be recognized, if you finds a “Device Management” applet in Control Panel. If you hit refresh and the info-screen shows a current refresh time everything is up and running.
If not, go to the \temp\dmclientlogs folder on the device and start troubleshooting with the logs for setup and operation that can be found there.
Very common problems here are connectivity, DNS name resolution, wrong version settings and security problems accessing the enrollment server or management point.

 

Alexander

 

 

 

 

Advertisements

Actions

Information

3 responses

12 01 2011
Rich

I’m trying to install this onto a Windows Mobile 6.1 device, and I’ve written what I think are the right settings into clientsettings.ini, but the DmClientSetup logs say:

“Invalid line: “@ùÿÿ0″”
“Bad ClientSettings.ini”
“Bad line number: 140”

But I can’t see any problem with my ini file. I can’t see any “@” symbols in the file, and line 140 looks fine to me.

Does anyone have any ideas?

Thanks,

Rich

12 01 2011
alexwech

Hi Rich,

try to see what exactly is at line 140. Maybe it it is just the setting that is wrong.
Be sure to open the file in notepad or a any editor not applying text formatting.
Could it be a missing colon in the comment line before?

HTH
Alexander

13 01 2011
Rich

I managed to fix this by deleting all comment lines from the file (every line starting with “;”).

Perhaps some of the commented out text was confusing the ini parser used by the client app.

This seems strange to me, as I didn’t change any of the comments — they came with the example ini file from the SCCM install.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s




%d bloggers like this: