Disclaimer

Lets start this post pointing out that this is an incredibly hacky (read: bad) way to recover the (mostly default?) sshd_config file on an ESXi installation. It turns out when I first made the change, I did not test that it actually persisted after reboot and didn't find out until after I installed an update, 262 days after the last configuration change. Oops. I definitely don't recommend doing this unless you have no other choice and don't have support from VMware.

As with everything you read online, I provide no support, warranty, or any other claims if you follow these steps, and am not responsible if you mess up your installation!

Background

With all that out of the way, let me set the stage. My ESXi instance is hosted in a remote co-located center, without a remote IP KVM (since I am too cheap to pay for one). Not exposed to the internet, I need to VPN in to get access to the web console (HTTPS) or SSH. This has served me well for the last half year, and even with the VPN requirement, I also edited the SSHD configuration file to require private key access and disable the root user from logging in via SSH (security in depth).

The update

The server had an uptime of 262 days since the last reboot and I decided to apply the latest ESXi update. After the update, I could log in via the web console, but SSH access was denied. Even though it seems conveniently timed, the update did not cause any of these problems. This would have occurred if the server rebooted for any other reason.

I originally followed this VMware KB article on how to secure SSH. I diligently copied my SSH keys in to /etc/ssh/keys-<username>/authorized_keys as described. What they fail to mention is that the keys do not persist after a reboot. The changes to sshd_config do persist, however, which is why I was left with keys that could log in to root, but PermitRootLogin no was still set. I had lost SSH access to my instance.

Confirming SSH Keys

During the troubleshooting process, I came across some neat ways to verify and set the SSH keys for the root account. I didn't see much in the way on how to do it. The endpoint to use is hosted at the same site and port of your web console, so if you access your console via https://server/ui you can access files via the /host path: https://server/host.

From what I have been able to gather, accessing this endpoint to upload files requires both Basic authorization as well as sending a vmware_client=VMware cookie when sending the PUT request.

% $creds = Get-Credential

PowerShell credential request.
Enter your credentials.
User: esxi-admin
Password: ****

% $r = Invoke-WebRequest `
>> -Credential $creds -Authentication Basic `
>> -SkipCertificateCheck `
>> -Uri "https://server/host/ssh_root_authorized_keys"

% $r.Content
ssh-rsa AAAA...

% $keys = "$($r.Content)`n$(Get-Content ~/.ssh/esxi.pub)`n"
% $keys
ssh-rsa AAAA...
ecdsa-sha2-nistp256 AAAA...

% Invoke-WebRequest -Credential $creds -Authentication Basic `
>> -Uri "https://server/host/ssh_root_authorized_keys" -SkipCertificateCheck
>> -Method PUT -Headers @{Cookie="vmware_client=VMware"} -Body $keys

StatusCode        : 200
StatusDescription : OK
...

Attempting to create a custom VIB

After getting a new SSH key on the server and confirming that it doesn't work for my admin user or root user, I finally had the wherewithal to check the logs on the web console, and finding that root login wasn't even being attempted because root access was deined. That means my sshd_config file was still intact after the update, but the keys for my admin user were missing and root was blocked from logging in. How can I go about getting access? It turns out a custom VIB was the solution! Or so I thought. While I ran in to several posts on the subject, nothing really worked to the extent I was hoping for. NOTE: this is where having physical access would have allowed me to fix the file and be on my merry way. If you have physical access, USE IT!

First issue is that without VMware's blessing, you cannot create a "community" bundle file that has permissions to the core system (/etc, /usr stuff) but could write to /opt or create firewall rules. Unfortunately, I needed to fix the sshd_config file, so a community version was not going to work, and let me tell you, I tried. I went through the process of grabbing VMware's VIB builder program, getting SuSE Enterprise Linux 11 SP2 to run (see firewall link above for directions, don't go higher, it won't install the tool!), building and deploying my file. I even came across a way to use "partner" files without VMware's signature, however that only works in a setup with vSphere. I found I could even force the install of my community VIB ... if I had SSH access.

Nothing I found would work in my scenario, though curiously every search I had that involved "ssh" and "vib" kept returning results for some VMware community Department of Defense thing, which I kept ignoring, because why would I need some DOD thing? Well, as I was about to order an IP KVM, I decided to check out the link.

Finding the "right" VIB

Having had a crash course in how VIBs work and their terminology I was able to read through and understand the instructions on what the VIB actually did, which I figured would be quite complex. All it does is edit 4 files in your system:

• /etc/issue: adds a super scary login banner warning about accessing United States Government infrastructure

• /etc/pam.d/passwd: updates password complexity requirements

• /etc/ssh/sshd_config: "adds necessary daemon settings"

• /etc/vmware/welcome: adds the same super scary warning to ESXi's direct console screen (physical access).

Reading deeper, the DoD VIB also comes in two flavors: enable root SSH access and deny root SSH access. Bingo! The changes in the VIB were safe enough that it wouldn't impact the system and it will set PermitRootLogin to yes! I quickly downloaded the zip file and promptly used the dod-stigvib-67-re-1.0.0.1.14639231.vib file. Et voilà, I had SSH access to my system again through the root account! Not wanting root access, I promptly disabled it again after setting my admin user's keys again. Or so I was hoping. It turns out that when you have files managed by a VIB, you cannot edit the files, even as the root user. I uninstalled the DoD VIB and crossed my fingers.

I still had access!

Using a shell script to set SSH keys on reboot

With access restored for the root user and the DoD customizations removed I had full access back to the configuration files I needed. I still want to disable root access to SSH and somehow persist my esxi-admin's keys after a reboot. How to pull this off?

It turns out that I had actually found the answer in my previous VIB author searches. While the directions are listed for ESXi 4.x/5.x, they also work fine on 6.x as well. Custom files, such as /etc/ssh/keys-<username> are not backed up by the system, and you cannot force it by creating .#files or other means, it turns out you can edit /etc/rc.local/local.sh and have it backed up and persisted across reboots! Once I found these nuggets I found people copying SSH keys to the persisted volume mounts and copying it to a local ~/.ssh file for the user. Since I have a single user and my root account is effectively disabled, I opted for a simpler approach of copying the SSH keys from the root user to my user on boot.

mkdir /etc/ssh/keys-esxi-admin
cp /etc/ssh/keys-root/authorized_keys /etc/ssh/keys-esxi-admin
chown esxi-admin:esxi-admin /etc/ssh/keys-esxi-admin/authorized_keys

So there you have it, a way to recover SSH access due to a modified sshd_config file without needing physical access (but needing web console access). If you have physical access, please use it instead of this long thread of bad ideas. As stated at the beginning, I am not responsible if you use this and completely break your installation. No warranty, support, etc is implied.

Identifying the device

The first thing I needed to do was define the name I wanted to use in the container. My current Docker setup uses the /dev/ttyUSB0 and /dev/ttyUSB1 devices directly. I know you can give them better names via udev so let's do that!

First I needed to identify the device and grab some useful static identifiers.

user@host:~$ udevadm info -a /dev/ttyUSB0
  looking at device '/devices/pci0000:00/0000:00:14.0/usb2/2-4/2-4:1.0/ttyUSB0/tty/ttyUSB0':
    SUBSYSTEM=="tty"
    DRIVER==""

  looking at parent device '/devices/pci0000:00/0000:00:14.0/usb2/2-4/2-4:1.0/ttyUSB0':
    KERNELS=="ttyUSB0"
    SUBSYSTEMS=="usb-serial"
    DRIVERS=="cp210x"
    ATTRS{port_number}=="0"

  looking at parent device '/devices/pci0000:00/0000:00:14.0/usb2/2-4/2-4:1.0':
    KERNELS=="2-4:1.0"
    SUBSYSTEMS=="usb"
    DRIVERS=="cp210x"
...
    ATTRS{interface}=="HubZ Z-Wave Com Port"
...
user@host:~$ udevadm info -a /dev/ttyUSB1
  looking at device '/devices/pci0000:00/0000:00:14.0/usb2/2-4/2-4:1.1/ttyUSB1/tty/ttyUSB1':
    KERNEL=="ttyUSB1"
    SUBSYSTEM=="tty"
    DRIVER==""

  looking at parent device '/devices/pci0000:00/0000:00:14.0/usb2/2-4/2-4:1.1/ttyUSB1':
    KERNELS=="ttyUSB1"
    SUBSYSTEMS=="usb-serial"
    DRIVERS=="cp210x"
    ATTRS{port_number}=="0"

  looking at parent device '/devices/pci0000:00/0000:00:14.0/usb2/2-4/2-4:1.1':
    KERNELS=="2-4:1.1"
    SUBSYSTEMS=="usb"
    DRIVERS=="cp210x"
...
    ATTRS{interface}=="HubZ ZigBee Com Port"
...
user@host:~$

Based on some very helpful posts, I was able to figure out the pieces I needed to define my udev rules.

Creating a udev.rules file in /etc/udev/rules.d/99-gocontrol.rules I added the following.

SUBSYSTEM=="tty", ATTRS{interface}=="HubZ Z-Wave Com Port", SYMLINK+="zwave", MODE="660", GROUP="1500905492"
SUBSYSTEM=="tty", ATTRS{interface}=="HubZ ZigBee Com Port", SYMLINK+="zigbee", MODE="660", GROUP="1500905492"

I then reloaded the rules and triggered udev to rescan devices.

user@host:~$ sudo udevadm control --reload-rules
user@host:~$ sudo udevadm trigger
user@host:~$ ls -l /dev/ttyUSB*
crw-rw---- 1 root 1500905492 188, 0 Sep 22 23:23 /dev/ttyUSB0
crw-rw---- 1 root 1500905492 188, 1 Sep 22 23:23 /dev/ttyUSB1
user@host:~$ ls -l /dev/z*
crw-rw-rw- 1 root root 1, 5 Sep 22 23:18 /dev/zero
lrwxrwxrwx 1 root root    7 Sep 22 23:18 /dev/zigbee -> ttyUSB1
lrwxrwxrwx 1 root root    7 Sep 22 23:18 /dev/zwave -> ttyUSB0
user@host:~$

Yay! The devices have an updated group ID and the symlinks match the device names in a more reliable way. Note the symlinks are still owned by root since symlinks themselves cannot have permissions assigned, they just point to another file in the file system, they can, however have an owner and group assigned, but in this case it's inconsequential. Now that the devices have been created, I need to map them inside the container.

Binding the devices to the container

To bind the devices in the container, I need to configure both the machine's .nspawn file in /etc/systemd/nspawn as well as the service startup file .service. I'm using systemd's nspawn's template file, so I take advantage of the override logic systemd provides rather than create a standalone template file. This lets any changes provided by the system to provide the base while I augment it with the couple settings I need.

The first thing I need to do is map the device in /etc/systemd/nspawn/home-assistant.nspawn. (The name of the file is the same name of the container, you'll see it again in the service file as well.)

# /etc/systemd/nspawn/home-assistant.nspawn

[Files]
Bind=/dev/zigbee:/dev/zigbee
Bind=/dev/zwave:/dev/zwave

The Bind= directive in the .nspawn file will the host's file on the left of the : to the container's path on the right. In this case, it's a direct mapping of /dev/zigbee from the host to the container.

The default container template systemd uses to launch a container is correctly restrictive when it comes to device access, so we need to override the configuration to allow our devices through. If the container is running, you can run sudo systemctl edit systemd-nspawn@home-assistant.service and systemd will take care of creating the correct path and override file for you. However, if the container is not running, the service will not exist and the command will fail.

// if the machine is running, you can edit the override with this
user@host:~$ sudo systemctl edit systemd-nspawn@home-assistant.service

// or, if the machine is not running, you need to create the directory
// and override file yourself.
user@host:~$ sudo install -d -m 0755 -o root -g root /etc/systemd/system/systemd-nspawn@home-assistant.service.d
user@host:~$ cd /etc/systemd/system/systemd-nspawn@home-assistant.service.d
user@host:/etc/systemd/system/systemd-nspawn@home-assistant.service.d$ sudoedit override.conf

We need to add two DeviceAllow= directives to let the devices map inside the container.

# /etc/systemd/system/systemd-nspawn@home-assistant.servce.d/override.conf

[Service]
DeviceAllow=/dev/zigbee rwm
DeviceAllow=/dev/zwave rwm

The DeviceAllow= directive grants access to the device based on the second string provided, in our case rwm. The rwm allows (r)ead access, (w)rite access, and the ability to (m)ake the node.

Verifying the devices show up in the container

All that is left is to restart the container, get a shell, and verify the device listing.

user@host:~$ machinectl poweroff home-assistant
user@host:~$ machinectl start home-assistant
user@host:~$ machinectl shell home-assistant
root@home-assistant:~$ ls -l /dev/ttyUSB*
ls: cannot access '/dev/ttyUSB*': No such file or directory
root@home-assistant:~$ ls -l /dev/z*
crw-rw-rw- 1 root   root      1, 5 Sep 22 23:43 /dev/zero
crw-rw---- 1 nobody dialout 188, 1 Sep 22 23:23 /dev/zigbee
crw-rw---- 1 nobody dialout 188, 0 Sep 22 23:23 /dev/zwave

Boom! That's it, we're done! Eagle-eyed observers will notice that the owner is nobody and not root. This is the flip side of the private-user-coin. On the host, root owns the device and 1500905492 is the group. Inside the container, the opposite is true, the owner is the special nobody wildcard since it can'tresolve the real root owner (because the root account is actually 1500905472 inside the container) but the group is properly matched to dialout since the gid in the container is 20, and hey would you look at that, 1500905492 is 20 higher than 1500905472!

If you look a little closer, the original /dev/ttyUSB0 and /dev/ttyUSB1 devices are not in the container, and that's OK! Instead of simply binding the symlink (as what usually happens in a bind) the nspawn process created new device nodes for us, with the correct 188, 0 and 188, 1 device identifiers.

Granting access to VMWare ESXi

The ESXi server is set up to allow SSH access with public key authentication only, so it does not have an IP allow list configured. This is quite fortuitous as it gives me a steppingstone to get back in without opening a support ticket with my hosting service. The main step here was to SSH in to the ESXi host, remove the old IP address and add the new IP address to grant access to the web services. The ESXi host is running 6.7, so the steps may be different on ESXi 5 or 7.

[home]% ssh esxi.host
# authenticate via public key

[esxi]% esxcli network firewall ruleset allowedip list --ruleset-id=vSphereClient
Ruleset        Allowed IP Addresses
-------------  --------------------
vSphereClient  1.1.1.1

[esxi]% esxcli network firewall ruleset allowedip remove --ruleset-id=vSphereClient --ip-address=1.1.1.1
[esxi]% esxcli network firewall ruleset allowedip add --ruleset-id=vSphereClient --ip-address=1.1.1.2

# no output is produced with the add/remove commands, so verify the
# change took place
[esxi]% esxcli network firewall ruleset allowedip list --ruleset-id=vSphereClient
Ruleset        Allowed IP Addresses
-------------  --------------------
vSphereClient  1.1.1.2

With that, you can access the ESXi web interface.

Granting access to the OPNsense router

Another appliance in my setup needing an update to the IP allow list is my OPNsense router, so I can access the configuration interface and update the IPsec tunnel settings. This requires access to the ESXi web interface to get console access to OPNsense. Once in the shell, adding the public IP address to the allowed_config PF table is quite straightforward.

[opnsense]% pfctl -t allowed_config -T add 1.1.1.2

Do not bother removing the old IP address as any change in OPNsense will replace any changes here, so immediately go and update the rule alias and swap out the IP addresses.

Firewall > Aliases > Edit allowed_config entry

Edit the alias and remove the old 1.1.1.1 address and add the 1.1.1.2 address and apply the changes. Clear the console and log out. You are done with ESXi at this point.

Updating configured WAN IP on the UniFi Security Gateway

Due to an incomplete configuration (more on that on the future IPsec setup post) I decided updating the UniFi Security Gateway (USG) would be next on the list since the USG is unable to successfully connect the IPsec tunnel when initiated from the USG to the OPNsense router.

I loaded up the local UniFi Network Controller interface, jumped into the settings section, and updated the "Local WAN IP" with the new public IP address.

Settings > VPN > VPN Connections > Remote Network

Replace the old WAN IP Address field with the new one and click "Done" at the bottom of the page. While you are working on the other steps, the USG will provision the changes and be ready for incoming IPsec tunnels.

Changing the Remote Gateway address in OPNsense IPsec Tunnel Settings

The last piece of the IPsec tunnel puzzle is to update the Remote Gateway IP address configured in the OPNsense IPsec tunnel settings. You will need to edit the Phase 1 entry for the IPsec configuration you are updating.

VPN > IPsec > Tunnel Settings > Edit the Phase 1 rule entry

Update the "Remote Gateway" field with your new public IP address, click "Save" at the bottom of the page, and then click "Apply changes" in the upper right of the next page in the notification banner.

Probably Unnecessary Steps

At this point, you are pretty much good to go. With my current configuration, the USG cannot initiate the connection to OPNsense (for some reason, it attempts to use a certificate to authenticate when it should be using a Pre-Shared Key) so I initiate the connection from OPNsense by navigating to VPN > IPsec > Status Overview and clicking the play icon on the IPsec tunnel to restart the connection. Now, since everything is reconfigured correctly it should work.

In my case, the tunnel was set up, but no traffic would route through the tunnel. I could see IPsec packets passing by in the live firewall logs, but no responses were coming back. I double checked other areas to ensure the public IP address did not appear in other potential configuration areas: the configured gateway, and static routes. Everything seemed fine. Since the USG has issues connecting, I tried forcing a provision of the configuration profile, and when that did not fix the issue, I restarted the USG. Much to my surprise, restarting the USG did not fix the issue either.

I double checked the strongSwan configuration on both sides with the --list-conns and --list-sas and confirmed they had identical settings (this was a sticking point that will most likely be detailed in the future post) and monitored the connection setup with --log, everything appeared to be configured correctly and the two endpoints were talking and able to ping the endpoint address on the other side of the tunnel. Running out of options and about to pull my hair out in frustration, I tried the final thing I could think of: I restarted OPNsense.

It worked and my IPsec tunnel is back up and operational! My only guess is that there was some residual routing or other configuration left over in OPNsense that even restarting the strongSwan service did not fix. Maybe there was a route left over that could not update? I have no idea. Either way, I hope you will find this guide helpful, and that my future self will check back here the next time my house's public IP address changes.

Installation & Setup

Installation is as straightforward as it can be, simply download the source, and extract the purpleair directory in your <config>/custom_components directory (where <config> is the directory that contains your configuration.yaml file. Restart Home Assistant to get it to pick it up, and add the integration via the GUI.

Adding the sensor couldn't be easier (well, it could be, but this was a one-day project)!

1. Navigate to the PurpleAir Map.

2. Find the nearest sensor to your location. It could be down the street or a couple counties over. It all depends on where you live!

3. Click on the sensor, and click on the "Get This Widget" and copy the "JSON" link (this is the annoying part).

4. Paste the URL in the integration dialog and submit. You should be golden!

Notes

There are a couple things to note though!

• This was a one-day project, so it only supported what I needed to accomplish at the time.

• It does not support accessing the local sensor data directly on your network. I don't have a device here to test with. To support batching, the API URL it uses is hard-coded.

• It batches the API calls in an attempt to be nice to the free API service provided. It polls every 5 minutes and batches all configured sensors together. (PurpleAir updates their data every 2 minutes) This means that if you add a second station, it can take up to 5 minutes before the station starts showing data.

• It averages out the data on stations that have two sensors. There was an attempt at determining a "confidence" score associated with it and trying to surface that somehow. I couldn't find any supporting documentation on how PurpleAir does it for their map, so it's left undone at this point. This does mean that if you have a sensor that's wildly out of whack, your AQI will reflect it accordingly. If it becomes an issue, I'll look at addressing it. You can see the confidence of the station by looking at the station card and looking for the small ✓100% label (I've only ever seen 100%).

• There is NO ERROR HANDLING in this. Like, at all. If the network goes down or the API changes, it'll fail with error messages in your log file. If you want some insight on what it's doing, you can add the following snippet to your configuration.yaml file to get debug logging enabled for the component:

  logger:
    default: info
    logs:
      custom_components.purpleair: debug
  

Fancy-factor Dashboard Cards

To up the fancy-factor in displaying the AQI data, I ended up using the mini-graph-card and a little Lovelace configuration. It's amazing how far Home Assistant has come to be able to add this level of customization while keeping it relatively easy to use and extend.

It's nothing much, it's a vertical stack with the mini graph card, and an entity list beneath it. To increase the visual information, the graph lines use the color threshold option to match the standard AQI color scheme. If you want a similar setup, here's the YAML for the whole setup. Simply copy out the mini-graph-card part if that's all you're interested in.

type: vertical-stack
cards:
  - type: 'custom:mini-graph-card'
    entities:
      - sensor.broadlake_view_air_quality_index
    line_width: 5
    points_per_hour: 4
    hours_to_show: 6
    show:
      legend: false
      labels: false
    color_thresholds:
      - value: 0
        color: '#68e143'
      - value: 50
        color: '#ffff55'
      - value: 100
        color: '#ef8533'
      - value: 150
        color: '#ea3324'
      - value: 200
        color: '#8c1a4b'
      - value: 300
        color: '#731425'
  - type: entities
    entities:
      - entity: air_quality.broadlake_view

Please let me know if you use it or if you have any problems. You can reach me on the Home Assistant forums or open an issue in the repository.

Imported Comments

Adam on Monday, August 19, 2013 at 10:38 PM wrote:

Thanks for taking the time to write this up! Its exactly what I was looking for. I think the only think missing was I had to chown on the file to root in order for "sudo launchctl load <filename>" to work.

Imported Comments

Paolo Rodríguez on Monday, December 24, 2012 at 9:52 PM wrote:

You are fantastic, thank you very much for this tool.

Nicolas Lagalaye on Thursday, February 7, 2013 at 8:23 AM wrote:

The tool is great, thanks for sharing it. So good it is a command line one: clear and straightforward. As for 2.0 version, will it be able to import unmanaged accounts or only evict? I'm so looking forward to it!

Talidorn on Monday, February 25, 2013 at 11:51 PM wrote:

The reason that the users of your script can only add 5 alias addresses is that you are limited to 15 max... 5/year. So, add 5... add a reminder to add another 5 on your calendar for next year and then add them... then add a reminder to add another 5 on the 3rd year (2 years from first alias addition) to add the remaining 5.

tada! 3*5=15.... and you are all maxed out.

Stuart on Friday, April 5, 2013 at 9:03 AM wrote:

I've just tried using your tool for the first time to add an alias to an account and am getting the SoapException error:

"Creating alias...The call failed with outcome:

SoapException Error 3001: Invalid member name."

The email address that I'm trying to add an alias for also has a Windows Live account with the same name - does this mean I can't add aliases to this email?

Stuart on Friday, April 5, 2013 at 10:22 AM wrote:

Found my issue - I wasn't using the full email address for the alias. Working great now. Thanks for the tool!

Administrative Credentials

This isn't explained very well in the program itself, but you'll need to provide some admin credentials to use the remote service. By administrative credentials I mean that you'll need to use an account that not only manages the domain the user's account logs in with but it will also need to manage the domain of the alias. If the alias you're adding or removing exists in the same domain as the user's login domain, you'll generally be fine. If you're adding or removing a domain that is not related to the login domain, you'll need to make sure your admin account can manage both (i.e. both domains are listed when you log in to domains.live.com).

Listing known alaises

Ok, this one is pretty straight forward, you'll run wlalias list email@address to show the currently assigned aliases for the user. The documentation states that the parameter is the "fully qualified member's name" which I've found to be their login email address. If the user is found and is a part of your managed domains the aliases will be printed.

C:\wlalias\bin>wlalias list test_user@gibixonline.com

Please provide administrative credentials for the domain to manage.
Username: come-on.really?@gibixonline.com
Password:

Known aliases for test_user@gibixonline.com
    test_user3@gibixonline.com
    test_user5@gibixonline.com

Adding a new alias

Creating an alias is just as straightforward as the rest of the application. In this case you'll run wlalias add login@email newalias@email and provide the admin credentials as usual. Just as a note, both the login email and the new alias must be "fully qualified" as described above. Sadly the application has to do a little guess work here since Microsoft is lying. When calling the CreateAlias method the documentation says:

Return Value

An XML block that contains a list of alternative names. The following is an example of the XML block. [...]

Well, as much as I'd love to believe that, I've never, ever received an XML block of alternative names. All I get back s a hash of some sort that doesn't correlate with anything that I know of. I've followed all of their directions as best I could and can't seem to find where the problem might be. I suppose I can use Fiddler and see if it's actually returning the wrong data or if it's the implementation, but that's for another day. Instead, the application will then call to list the aliases a second after creation and see if the alias is in the list and let you know accordingly.

C:\wlalias\bin>wlalias add test_user@gibixonline.com test_user6@gibixonline.com

Adding alias test_user6@gibixonline.com to account test_user@gibixonline.com.
If this is incorrect, press ^C or press escape in the password entry.

Please provide administrative credentials for the domain to manage.
Username: teehee.heehee@gibixonline.com
Password:

Creating alias...done.

The server returned: 0003CEEB822590A9

According to the docs the server should've returned the alias
as the result. Since it didn't, I'm checking the alias list of
the user name to see if it's listed.

The alias was found.

Removing an alias

After the previous two sections, this one will be the shortest. It's very close to the previous command except that you give it the address to remove, wlalias remove login@address alias@address. It takes two parameters: the fully qualified login name and the alias to remove. There is no return value from this call so all I have to go on is the fact that the server didn't return an error when being called.

C:\wlalias\bin>wlalias remove test_user@gibixonline.com test_user5@gibixonline.com

Removing alias test_user5@gibixonline.com from account test_user@gibixonline.com
.
If this is incorrect, press ^C or press escape in the password entry.
Please provide administrative credentials for the domain to manage.
Username: maybe?.nahnope@gibixonline.com
Password:
C:\wlalias\bin>

That's it, there's no output. Well, it'll mention something if it failed via HTTP. I suppose it could've checked like it did during creation but I didn't add it this time.

Future

While the tool is functionally complete, I do plan on making a few modifications in the future. As I was testing, I got tired of typing in the password and realized that this tool cannot be easily automated at this time. I was thinking of allowing you to store the username and password in envrionment variables and using those if they exist. Honestly, I just didn't want to deal with handling a password coming in via the command line. Also, with my current method, your password is secured and only exists in a readable format for less than a second (during the Authentcation() call). If I allow automation, that means your password will exist as a full string in memory that I won't be able to clear when I'm done. My other thought is to clean up the output and make it a bit easier to read. I was also thinking of expanding this to allow some other management of Windows Live, but we'll see.

If you made it this far, I congratulate you. You must have missed the download link I put in the first paragraph. The official download source of the application will always be on the project's repository, so be sure to download it from there.

If you have any issues, please feel free to create a new issue on wlalias' issue tracker. If I remember right, you won't need to sign up to create one. If you want, you can also contact me through my blog and I'll try to respond.

I can only hope that you find this tool useful. Once again, download wlalias 1.0 and create aliases with (relative) ease!

Imported Comments

Garry on Thursday, November 1, 2012 at 7:10 PM wrote:

I've been waiting for ages for something like this. Worked great, thanks!!!

Anonymous on Friday, December 14, 2012 at 4:22 PM wrote:

It was working fine for a day or so. Now it just gives me errors, even though all information is correct. Seems MS changed something to prevent us from adding aliases?

Errors I get now:

Creating alias...The call failed with outcome: SoapException

An exception occurred too! (sorry): PassportError: Passport error.

Aero on Friday, December 21, 2012 at 3:11 PM wrote:

Awesome tool.

Where can we find the API documentation - trying to figure out what else we could do with our Domains for Windows Live accounts ...

Joshua on Sunday, December 23, 2012 at 8:20 PM wrote:

Anonymous: I'm working on an update to the tool to be a bit more descriptive in the error messages. The most common error has been trying to create a new alias for an address that's already in use by an actual account.

Aero: The documentation is available on MSDN under the Windows Live Admin Center SDK Reference at http://msdn.microsoft.com/en-us/library/bb259710.aspx.

Aero on Tuesday, December 25, 2012 at 12:21 PM wrote:

Thanks Joshua!

Tom on Friday, January 13, 2013 at 11:34 AM wrote:

Thank you for a great utility. I never understand why Microsoft don't publish these possibilities clearly. I was impressed that I have two domains and can alias between the two.

I have wanted the alias feature for years, thank you again.

Jeff on Thursday, February 21, 2013 at 5:27 AM wrote:

Great tool!!

Do you have anything to add a domain alias also? So anything sent to mail@example2.com would be redirected to mail@exemple.com.

thanks a lot!

Steven on Wednesday, March 20, 2013 at 10:04 PM wrote:

@Jeff

I have an account with 2 domains in it, and I was able to add x@x2.com as an alias on the x@x1.com account fine. I think you just have to have registered both domains.

Steven on Wednesday, March 20, 2013 at 10:09 PM wrote:

I'm getting "not authorized for this operation" on my own domain, but when I do it for an account I set up for business it works fine. Any thoughts?

Martin on Wednesday, June 26, 2013 at 11:57 AM wrote:

I have this problem:

Creating alias...The call failed with outcome:

Error 1004: Not authorized for this operation.

What happened?

Joshua on Wednesday, June 26, 2013 at 10:49 PM wrote:

There are a couple things that could be going on. First, I recommend you check out the application's site at http://wlalias.com and see if any information there helps you with your problem.

Off the top of my head some things you can check are:

• Make sure you've validated your Microsoft Account (meaning it has a phone number for backup and such). - Make sure the user you're signing in with can administer the domain (meaning it can log in to https://domains.live.com)

• If you have two factor authentication, you'll probably need to create an application specific password.

Good luck and let me know if you're able to get it fixed!

Keith on Thursday, August 1, 2013 at 9:08 PM wrote:

When I try to load to application it immediately closes. Any ideas? I have .net framework installed.

Joshua on Thursday, August 1, 2013 at 10:01 PM wrote:

Keith, the application is a command line program, meaning you'll need to open the command prompt to use it. There's a quick getting started section on the wlalias homepage at https://wlalias.com and the full documentation is at https://wlalias.com/help/.

Hope that helps!