Earlier this year I created a simple vSphere SDK for Perl script that allows you to update ESXi's DCUI (Direct Console User Interface) banner with multiple lines of text. I originally thought you could not customize the text color or the background color, though recently I found out that was not the case. While doing some testing on ESXi 4.1, I noticed two files (support,welcome) located under /etc/vmware and looking at the contents of support, it made realize we might be able to change the colors.
Here is the contents of /etc/vmware/support, notice the special formatting of the variables including color tags:
I decided to use one of my favorite UNIX utility, "strings" to take at the dcui binary that is located under /sbin in the Busybox Console (Tech Support Mode) and discovered you can control both the font color and background color. There are also special variables that can be used to display information about the ESXi host such as the product version or IP Address.
Here are the supported colors:
white
black
dark-grey
light-grey
yellow
Here are the special variables:
assettag
BIOSversion
BMCversion
CIM_Chassis
CPLDversion
esxproduct
esxversion
hostname
ip
license
memory
OMC_MCFirmwareIdentity
OMC_SMASHFirmwareIdentity
OtherIdentifyingInfo
PLSAversion
serial-number
servicetag
ssl-thumbprint
supportperiod
supportstart
VersionString
VMware_HHRCSoftwareIdentity
There are two ways of updating the DCUI welcome banner: using local or remote esxcfg-advcfg or manually editing /etc/vmware/welcome file.
Here is an example of using vCLI's esxcfg-advcfg:
Here is what that looks like on the DCUI:
As you can see, this is not easy if you want to update multiple lines. You would need to add a lot more spaces to force newlines, but this becomes tedious and pretty much unreadable. The second method is edit the welcome file that is located in the Busybox Console, which requires you to enable ESXi's Tech Support Mode. I wrote a quick Perl script called generateDCUIScreen.pl which accepts an input file and allows a user to customize the output and the script generates the "welcome" file which is uploaded to your ESXi host.
Here is an example of the input file:
The script will parse the input file which will contain definitions for:
- bgcolor and color as described above
- special variables as described above (must use braces for variables to be translated)
- custom text
- "=space=" string which is unique to my script which generates the newlines
The script requires that you have Perl, but you do not need to have vSphere SDK for Perl. For ease of use, I executed the script using vMA.
Here is an example execution using the input file from above:
You will need to scp the new"welcome" file to your ESXi host under /etc/vmware which is empty by default. For the changes to take effect, you will need to run the following command at the console:
kill $(ps | grep dcui | awk '{print $1}')
This will kill dcui utility and watchdog process will spawn a new instance causing the change to take effect Note: A reboot will also do the job, but be sure to run /sbin/auto-backup.sh before doing so, that way the change will be backed up.
Here is what DCUI screen looks like:
As you can see, you can control variety of pre-defined variables including hostname and IP Address and custom text for your organization. This is useful for those that do not want to expose all the information that available on the default DCUI screen, which may be a security concern for some organizations. A few things to note, I was not able to fill the entire screen like the default DCUI banner and the "welcome" file is character sensitive and you need to use tabs or white spaces to force the background to get filled. There is also a limit in the number of characters per row before it wraps to the next line.
I am sure there is someone out there that will create some interesting ASCII art, but here is my 5min free hand attempt at it 😉
This can easily be integrated into a scripted install using the new ESXi 4.1 kickstart feature.
Dominic Rivera says
That's f'ing awesome. You can shove down some of the welcome screen data with host profiles too, I'd be interested to see if you can do some of the same customizations and blast them out with host profiles. Nice write up and sleuthing.
Kendrick Coleman says
H4x teh ESXi... nice dude.
email says
mmm awesome
Anonymous says
Sorry for the silly questions; learning as I go... How can i execute generateDCUIScreen.pl using rCLI? Could you elaborate on this statement: "You will need to scp the new "welcome" file to your ESXi host under /etc/vmware". Am I supposed to replace the welcome file with the input file?
Shmuel says
Hello
I am trying to use this method but I find no dcui process .the /etc/vmware/welcome is updated ok.
OS ESX classic 4.1
Thanks ,
rub1
William says
@Shmuel
The article is only applicable to ESXi not classic ESX
Shmuel says
thanks William , I have overlooked it.
do you know maybe some way to pop up a message on the welcome screen of ESX classic from a perl / python Script
running on ESX host ?
the esxcfg-advcfg -m option changes the /etc/vmware/welcome, but I guess it is not used by the "welcome screen " here.
Dee says
do you know what is the keyword to display the cpu model and number of cpu model on the dcui. This would be similar to what shows up on the default dcui screen.
William says
@Dee,
No I do not
Dee says
Got around it by placing an init script that will generate 'welcome' everytime with cpu #s / model inserted ..
JC says
Nice! One question though. I have it in my kcikstarts and all works fine BUT when I 'Enable Local Tech Support' and go to the logon screen (Alt-F1) the text of the /etc/vmware/welcome file is displayed before the login prompt! And I mean the actual TEXT - not the translation. Also, I get the exact same behavior if I do it manually after the build is complete.
William says
@JC,
That's expected, DCUI isn't running in that console (tty). Also if you login and take look at /sbin/tech-support.sh you'll see that if /etc/vmware/welcome exists, it'll just cat that out. Also depending if you've enabled local TSM, you'll either get a login prompt or TSM unavailable. This display trick only works when DCUI utility is running and will display whatever you have configured. Also if you login and do a ps -Cc | grep dcui, you'll see that it's running by default in tty2
JC says
Thanks - I'll see if I can modify the tech-support.sh script to NOT do that 😀
Afthab says
Anyone help me,
i simply edited "welcome" file and successfully displayed. Then i removed the line now its showing blank screen. How can i get back default display ?
Chris C. says
Thanks for this post! I've combined stuff from your tutorial with a script that is run by cron every 5 minutes and gets the status of my guests using vim-cmd and outputs them to the screen.
Anonymous says
Are there any other variables that /etc/vmware/welcome will process?
-Zack
Ivan says
very good job
Behnood Moradi says
Hi,
did you know the parameters for CPU model and quantity in welcome file?
Thank, Excellent
Stephen Moll says
Your list of supported colours is missing one: Red
Other than that, very interesting. I hadn't realised the welcome message was so flexible. It's shame vCenter AUP/notice isn't as flexible, more disappointingly the message is hidden unless the user clicks a link.