Introduction
When you've just unpacked your first stack of VXC devices, the entire set of documentation may be a bit overwhelming. The main questions we've been seeing is customers wondering how to best manage their devices. There are ini-files, there is the VXC Manager, you can put an FTP or HTTP server, ... etc, but what serves what purpose and when would one use either of those things?
Everyone who is going through, or has gone through this will know exactly what I'm talking about. The goal of this document is to get rid of that, and hopefully bring some structure in what may appear to be chaos.
There are basically main 3 options to manage the endpoints:
- On the device itself
- By using VXC Manager
- By using an FTP or HTTP file server only
Method 1 should be the least preferred method. Lots of customers have asked us how to disable the autologin on the VXC 6215 but that's not the goal. You need to run as thinuser to be able and leverage all the UC capabilities of the 6215 for example (cfr.: https://supportforums.cisco.com/docs/DOC-25080).
For quick demo's it will do, for normal to large deployments it is not scalable at all. For the VXC 6215 you would be unable to demo the UC capabilities as admin user.
Options 2 and 3 will use ini files, and that's the way to go. Realizing that immediately starting with ini files is not so easy, I hope this document can take away doubts and fears you might have.
Before going more in depth on options 2 and 3, let's first talk a bit about how the VXC clients actually handle those ini files.
Folder Structure
The VXC 6215 has the following folder structure in mind:
+ Cisco | +--+ WLX | | | | | +-- wlx.ini | | | +-- <mac-address>.ini | | | +--+ bitmap | | | | | +-- cisco.gif | | | +--+ Certs | | | | | +-- equifax.crt | | | +--+ INI | | | +-- user1.ini | | | +-- user2.ini | +--+ ADDONS | | | | | +-- directory (text file) | | | +-- *.rpm (add-on RPM files) | +-- latest-image.raw | +-- latest-image.raw.info
The VXC 2000 has the following folder structure in mind:
+ Cisco | +--+ WNOS | | | | | +-- wnos.ini | || +--+ inc
| | |
| | +-- <mac-address>.ini
| |
| +--+ bitmap | | | | | +-- cisco.gif | | | +--+ cacerts | | | | | +-- equifax.crt | | | +--+ INI | | | +-- user1.ini | | | +-- user2.ini | | +-- ZC0_boot | +-- ZC0_wnos
As you can see, the structure of both the 6215 and 2000 series are very similar. The main difference is that the 6215 uses WLX whereas the 2000's use WNOS. Looking more closer to this folder structure the following is true:
- Firmware is put in the root of the folder
- wlx.ini or wnos.ini are global ini files for ALL VXC endpoints
- mac-address.ini file will contain more specific device configurations than the global wlx/wnos.ini file
- The bitmap folder contains the background logo for your VXC device
- Certs contains certificates
- The INI directory contains ini files for specific users with more specific settings than the global wlx/wnos.ini files and the mac-address ini files.
- The ADDONS directory doesn't exist for the VXC 2000 zero-clients as they do not support ADDONS
- The ADDONS directory must contain a file called 'directory' which contains all the RPMs it wants to expose to the VXC clients. Multiple rpms are separated by newline (one rpm per line, not comma separated)
- The ADDONS directory contains RPMs that can be installed on the VXC clients
This is the structure the endpoints will always look for. This folder structure would be exposed to them on an HTTP or FTP server, which may or may not be the VXC Manager and may or may not be in a package.
The question you're probably asking yourself now is "When should I use the VXC Manager and when not?". The answer is that Cisco requires you to use VXC Manager for production use. For quick lab tests you can quickly roll out an HTTP/FTP server but for production you will need to use VXC Manager.
At first VXC Manager might seem a bit strange to work with, but it really is not that difficult.
For now, just remember that a working FTP and/or HTTP service is required and that the VXC Manager is able to leverage that.
The folder structure must be kept in mind as that structure will either exist on your file server OR in the VXC Manager packages you'll be creating and managing.
Managing without VXC Manager
Even though we want you to use VXC Manager in the end, let us first describe how to manage your endpoints without VXC Manager. This will simply a few things and will make it easier to understand when we later on add additional information.
When you plug-in the device on the network, it will fetch its IP through DHCP. The DHCP server can provide a few additional options. Two of these are option 161 and 162.
DHCP Option 161:
This option would be a string representing the address of the FTP or HTTP server the VXC devices should connect to. If you only specify an IP address, the client will default to using the FTP protocol. If you prefix http:// it will use HTTP. In case you would be worried that someday the default protocol would change, you can also prefix ftp:// to demand the FTP protocol.
DHCP Option 162:
This option would be a string representing the path on the FTP/HTTP server relative to the root. The combination or concatenation of options 161 and 162 will be the full URI the VXC clients will use.
Example:
Option 161 "10.48.37.163"
Option 162 "Brussels/Cisco"
=> The VXC clients which get this from their DHCP Server will use ftp://10.48.37.163/Brussels/Cisco/ to find their files.
The VXC 6000 series will search their files in ftp://10.48.37.163/Brussels/Cisco/WLX/ .
The VXC 2000 series will search their files in ftp://10.48.37.163/Brussels/Cisco/cisco/WNOS/ .
Do note that the VXC 2000 automatically inserts "cisco" after the option-162-path, which does not happen for the VXC 6215.
With this logic, you could have another site with another DHCP scope and reuse the same FTP/HTTP server but another pat
So, there you go. If you now make the folder structure on your FTP/HTTP server like how the endpoints expect it, you will see the devices start requesting the wlx.ini and so on.
To edit the ini files, you would use a any texteditor available to you. To know what to put in the ini files, you can refer to the ini documentation:
VXC 2000 Series: http://www.cisco.com/en/US/partner/products/ps11499/prod_command_reference_list.html
VXC 6000 Series: http://www.cisco.com/en/US/partner/products/ps11976/prod_maintenance_guides_list.html
Example INI files can be found at the bottom of this document.
Bringing in VXC Manager
The above is without the VXC Manager, but keep in mind that the VXC Manager also configures HTTP and FTP server. So you can use the above logic as well with VXC Manager. However, with VXC Manager, you may prefer to work with packages.
A package is basically nothing more than what its name implies: a package of files that can be pushed to one or more VXC endpoints, where such package would hold the folder structure the VXC client expects with the addition of a script (*.rsp file).
In VXC Manager > Package Manager you can see a few folders. Within those folders you can see packages. These packages can also be found on the VXC Manager @ C:\inetpub\ftproot\Rapport . This folder is actually mapped to the virtual directory /MYWDM in IIS. So to access that folder over HTTP, you would browse to http://<vxcm server/MYWDM/Rapport/ .
The reason I'm telling this, the moment you push such a package to a VXC endpoint, the endpoint is set to go and fetch its ini files from http://<vxcm server/MYWDM/Rapport/<package name>/ and it will ignore the DHCP options 161 and options 162.
It is very important you are aware of this. Any time you want to deploy a new package to one or more VXC endpoints, make sure that the ini files in that new package are exactly what you want it to be. So if your intent is to make a little change to one or two parameters and test it out on a few VXC endpoints, you could first copy the wlx.ini file from the first package to your new package and then edit that one.
So how do the endpoints actually show up in VXC Manager?
- DHCP option 186 (VXC-M IP Address)
- DNS SRV Query for _WDMServer._tcp.domain.tld for VXC Manager (Pointing to an A-record pointing to the VXC-M IP Address)
- DNS CNAME Query for WDMServer.domain.tld, assuming port 80 as default
- DNS A Query for WDMServer.domain.tld, assuming port 80 as default
Once you have set that up correctly, you will see devices starting to show up in your VXC Manager.
At the left of your list of devices you see a little icon which is either coloured green, yellow or red. This gives you the status of the device from the perspective of your VXC Manager. Your VXC clients will check-in every so often to tell the VXC Manager they're alive and kicking. However it could be that due to whatever reason, a few checkins were missed. You could configure it that if one check-in is missed shows up as yellow. If more checkins are missed, you could colour it red, implying that VXC manager thinks the device is offline.
This is configurable in VXC-M by going to Configuration Manager > Preferences > Device Manager Preferences.
Below is a screenshot of my lab:
As you can see, here it is set to check-in every 6 minutes where if that is obeyed to, the colour will be green. Missing 1 check-in will turn the icon to yellow as a sort of warning sign. Missing 2 check-ins would show it as red. Obviously, this is to be configured per your own environment and can vary a lot to your own wishes and needs.
Back to device manager you can select your device get more details about it by clicking the little '+'-sign at the bottom right. This will expand a tabbed pane showing more details of your device.
Right-clicking your devices gives you some more options such as rebooting, wake-up-on-LAN, launching a VNC session to it and shadow the user, ... etc but the most important one for this document is 'Package Distribution Wizard' as that's what we're talking about in this doc.
More about Packages
Let's take a look at the VXC UC package that Cisco has on Cisco.com (http://www.cisco.com/cisco/software/release.html?mdfid=284004131&flowid=31902&softwareid=283802941&release=8.6&relind=AVAILABLE&rellifecycle=&reltype=latest)
If you haven't done so, download the VXC-Manager Package zip file, and extract it. You will see the following files:
- A file ending with extension .rsp
- A folder with the exact same name as the rsp-file holding a few other files.
Now look carefully at that folder.. do you see the directory structure of the 6215? It's exactly that! In the wlx folder you will find a very basic wlx.ini with only one very important line:
"InstallAddOns=vxc-........rpm"
This is the ini-directive which will tell the client to install that rpm from the ADDONS directory. So obviously, you would need to further tweak the wlx.ini to your own configuration.
The rsp-file can be opened with any texteditor available to you and has two sections: [Version] and [Script].
[Version] is like header information. This will be used by VXC Manager when being imported.
[Script] is the real script that will be executed when this will be pushed to the client.
Very important in that [Script] section is that you see 2 times RB. RB stands for ReBoot. You may wonder why it would reboot 2 times and that's a fair question. The answer is that upon a reboot, the VXC client will go and check its ini URL if there's any new things available. If both the firmware and ini file have been changed, it will only fetch the firmware and upgrade with it. The ini-file is now ignored. At the next reboot the device will repeat the same step and will find the configuration file has been changed.
So when building your own packages which may contain both updates in firmware and ini-files, it's a good idea to make sure it reboots enough times.
Lastly I need to mention also that in the [Version] section the string next to "Number=" should be exactly the same as your foldername (and hence filename minus the .rsp extension)!!
Alright, now that we understand how such package looks like, let's import it in VXC Manager. Go to Package Manager, right-click and select New > Package ... and pick the option to register a package from a script file (.RSP)
At the next page select the file path and click next to complete the import. Note that the package will be placed in the GUI under the folder that was defined in the [Version] section of the .rsp file. You can choose your own text here, and in such way create your own folders.
Once it is imported, you can also find it @ c:\inetpub\ftproot\Rapport\<packagename> as mentioned earlier. If you need to make any updates to your existing packages, there you could go and make a change. (And technically, then it behaves just as any normal FTP/HTTP server deployment)
Alternatively you could copy that directory to your desktop, make changes, and import it with a new name. Just remember that 'Number=', filename and directory name must all 3 be the exact same name!
Now you can push it to your devices. You can select one or more devices, right click them and choose the Package Distribution Wizard. Select your newly imported package and you're done. If you go to Update Manager, you will be able to see that a package has been scheduled at the time you wanted. It could be saying (Now) and you'd have the idea that it sits there but not doing anything. You must understand that the VXC-Manager doesn't really push these packages to the clients. Instead, it stages them, and every time a device checks in, and sees that the time it has is the same one as the one where we scheduled it at, it will start to process it. Key message here is: make sure your check-in time is not too long and make sure that the time on your VXC clients is in sync with your VXC Manager! If your check-in time is set too high, you can always force a reboot from VXC Manager, or right click the device and choose "Refresh Device Information" which forces the device to check-in.
Default Device Configuration
Finally you could setup a Default Device Configuration (DDC), so that any new device that checks-in, receives the same package. To do this, go to Configuration Manager > Default Device Configuration, Right click and select New Default Device Configuration. On the first tab you define for which type of devices you're creating this DDC. Then you select the package you want to deploy (can be a sequence of multiple!). Then you define when you want the DDC to be deployed and that's it.
INI file best practices
1. Make sure there's no caching of previous ini settings/packages during upgrades
It's recommended to put the following 3 lines at the top of your wlx.ini files:
IniFileSource=server
Update.Mode=Both
Update.Preserve_changes=no
Especially the Preserve_changes=no. If that is set to Yes, settings that were used with the previous version of firmware are cached.
Even if they would at some point be no longer compatible with the new firmware. It still remembers it had that setting set.
With this set to no, any new firmware update process will forget the settings, and then fetch a brand new ini file. During the package push this can be seen on screen:
Picture showing the endpoint saying it's not preserving changes
2. Only use the backslash to separate one-line commands over multiple lines
Sometimes we see customers putting a backslash "\" at the end of each line. This is not the intent of the backslash. Some commands - for example the CONNECT one has multiple extra options. Either all the options go on one line separated by spaces, or you put them below each other where you end each line with a backslash, except the last one! If you'd add a backslash after the last option the ini file parser would then take the next line in the ini file also as an option. That would cause your ini file not to be properly read. Also remember that if the parser sees unexpected things, it completely ignores the entire line.
3. When removing an ini setting, negate it
If you want to remove a setting, then you'd have to explicitly negate it. Else the previous setting is still cached by the client.
Alternatively, you could first push a factory reset package to the client, and then give the real package you want to give it. That way, there is no caching at all.
4. When changing settings, firmware, ... etc, reboot CLEANLY
As mentioned in the packages section above, the VXC 6215 will go and check if there's anything new it should look for at shutdown. If you want to be smart and just remove the power plug and reinsert it to save time, this process is skipped and you will not have the expected behavior.
Always do a proper shutdown or reboot.
Example INI file
; Below is a very minimal ini file I'm using in the lab
; =====================================
; -- Section 1: INI update settings
IniFileSource=server
Update.Mode=Both
Update.Preserve_changes=no
; -- Section 2: time related
Timeserver=10.48.37.151
Timeformat="24-hour format"
TimeZone="Europe/Amsterdam" ManualOverride=1
; -- Section 3: which addons to install
InstallAddons=vxc-8.7.1-771.sletc11sp1.rpm
; -- Section 4: Monitor settings
DisplaySettings=MON1 rotate-normal DDC
; -- Section 5: Connection Icons to put on the desktop
CONNECT=BROWSER \
Description="Citrix XenDesktop Environment" \
URL=bdsol-xenddc-01.dcn.lab \
AutoConnect=yes \
Mode=Kiosk \
AutoConnect=no \
LocalCopy=no
CONNECT=VMWARE_VIEWCLIENT \
Description="VMware View Environment" \
Host="10.48.37.159" \
DomainName="DCN.Lab" \
AutoConnect=no \
Ping=yes \
Interactive=yes
CONNECT=RDP \
Host=10.48.37.251 \
Description="Cedric's Machine" \
AutoConnect=no \
Sound=on
