Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
This page covers release notes for the iPXE Anywhere Web Service
Microsoft .NET Framework 4.5.2.
The user account executing the installation (installation account) must have Administrator rights on the server in which the web service will be installed.
License file (optional at this point)
SQL Database - This database stores info about PXE booted computers and their capabilities. Traffic to this database is very small and, if necessary, it may be hosted on SQL Express. The SQL Database does not have to be installed on the same server as the iPXE Anywhere Web Service, but the service requires access to and permissions on the SQL Server in order to create the database and also to interact with it.
Note: The installation software checks if the user executing the installation has sufficient privileges to create the SQL database, but does not actually create the database. The database is created by the Service at service startup. Once the installation is complete, SQL permissions granted to the installation account can be removed, but the service must retain permissions in case the database structure needs to be modified during normal operations.
NOTE: The installer does not validate the license file so if you select an old/expired license file the installer will continue but the iPXE Anywhere service will stop soon after starting!
Installation Files
iPXE Anywhere can be installed to any location, but we recommend it to be installed to the default directory. Once the service is installed, the installation folder should contain the following:
Main Service Executable - iPXE Anywhere Service.exe
Configuration File - iPXE Anywhere Service.exe.config
Main DLL - iPXEAnywhere.Persistence.EF.dll
License file - License.cab
License file - License.nfo extracted from License.cab
Microsoft .net dependency dll’s
PowerShell script - RequestActionScript.ps1
Readme.txt
End User License Agreement file
Folder – Reporting
Folder - SRSS 2014 Reports
Reports - .rdl files
Powershell Script – Import-2PSReports.ps1
Folder- SRSS 2016 Mobile Reporting
Reports - .rsmobile and .rsd files
Important: Ensure that the License.nfo file has been created. Use notepad to open this file and check that your license information is correct.
Service
The Windows Installer file will install a service called “iPXE Anywhere Service” which is started during the install. In the event that it is not started the first thing to check is the License.nfo file followed by the Port that iPXE Anywhere is configured to use.
Pre-Requisite
The reports require an installation of Microsoft SSRS.
It is necessary to create a Data Source in order for the reports to connect to the correct Database and tables within the reports.
Start Report Manager (SSRS Native Mode).
In Report Manager, navigate to the Contents page.
Click New Data Source. The New Data Source page opens.
Type a name for the item. A name must contain at least one character and it must start with a letter. It can also include certain symbols, but not spaces or the characters ; ? : @ & = + , $ / * < > | " /.
Optionally type a description to provide users with information about the connection. This description will appear on the Contents page in Report Manager.
In the Data source type list, specify the data processing extension that is used to process data from the data source.
For Connection string, specify the connection string that the report server uses to connect to the data source. It is recommended that you do not specify credentials in the connection string.
The following example illustrates a connection string for connecting to the local SQL Server iPXE Anywhere database:
data source=<SQLservername>; initial catalog=ipxeanywhereDB
For ‘Connect using’, specify how credentials are obtained when the report runs:
If you want to prompt the user for a logon name and password, click Credentials supplied by the user running the report. To use the credentials that the user enters as Windows credentials, click Use as Windows credentials when connecting to the data source. If the user name and password are database credentials, do not select this option.
If you intend to use the data source as a shared data source with saved credentials that are managed by the owner of the data source, or for reports that support subscriptions or other scheduled operations (such as automated report history generation), click Credentials stored securely in the report server.
If the database server supports impersonation or delegation, you can select Impersonate the authenticated user after a connection has been made to the data source.
If you want the report server to pass the credentials of the user accessing the report to the server hosting the external data source, click Windows Integrated Security. In this case, the user is not prompted to type a user name or password.
Installing the Reports
Once the Data Source is created in the step above, import the SSRS Reports using the PowerShell Script that is included with the iPXE Anywhere Files, named Import-2PSReports.PS1. The only required argument for this is the name of the SSRS Reporting Server where the files are to be imported and the Data Source resides.
Example: .\Import-2PSReports.ps1 –ReportServer MYSERVER
The iPXE Anywhere Service is configured via the 2PXE Server Configuration File – which is covered in full in the 2PXE Server Manual document as below:
There are 2 settings to consider within the 2PXE Configuration file:
ENABLEIPXEANYWHEREWEBSERVICE="0” Specifies to use iPXE Anywhere Web Service. 0 to disable, 1 to use reporting functionality only, 2 to move the entire request over to the web service + reporting. 3 is 1+2 and the ability to execute cmdline from iPXE WS in WiNPE
BootRequest = 1,
Syslog = 2
Using the resolved IPv4 Addresss of the iPXE Anywhere Web Service unless overridden by adding the <add key="iPXEAnywhereWebServiceIP" value="192.168.xxx.yyy"/> setting in this config.
ReportBootConfiguration = 4,
ReportDLStart = 8,
ReportDLComplete = 16,
ReportDLBoot = 32,
RunCmdLineWinPE = 64
For example:
A value of 62 (2+4+8+16+32=62) gives you all but BootRequest and RunCmdLineWinPE. Therefore
for iPXE and StifleR Integration you would have to set it to a minimum of; 2+4+8+16+32 = 62
IPXEANYWHEREWEBSERVICEURI=http://url:Port Specifies the address and Port for the iPXE Anywhere Web Service
Pretty simple – but be sure to enter the FQDN of the server and Port number that you chose when you installed the iPXE Anywhere Web Service correctly.
IMPORTANT: After setting the above parameters, you will then need to restart the 2PXE service.
If you decide to simply configure the iPXE Anywhere Web Service to collect status during the boot process, there is nothing else to configure. Events such as download start, download end, errors and success will be forwarded to the iPXE Anywhere Web Service database which are then visable through the iPXE Anywhere Reporting Server.
Note: It is also possible to create your own custom status events – see the iPXE Anywhere Scripting Guide for further info.
There are three basic reports included with the iPXE Anywhere Web Service – with more to follow. The iPXE Anywhere Database also includes SQL Views which are designed to make it easy for users to create their own reports.
Once installed, the Reports can be accessed via the SSRS Web Page. Navigate to - <2Pint Software\iPXE Anywhere> where you will see the three reports which are described below.
IPA_One_Hour_Summary
This report is updates every 60 seconds, and gives you an ‘almost live’ display of the current state of boot requests.
The ‘Current Health’ indicator will change colour as the Success Rate of boot requests increases or decreases. This is a top-level indicator to allow deeper investigation should the boot request statistics deteriorate for some reason.
Below the indicator is the main chart which details the statistics for boot requests for the previous 60 minutes. There are seven status levels for a boot request, and as systems progress through the boot process these statistics will update.
Below the main chart is a table detailing any issues reported for the last 60 minutes.
IPA_Main_Dashboard
This report provides more of a ‘Management Overview’ of performance over the previous 6 months. You can see trends, success rates and timings etc. for all boot requests here.
IPA_Hardware
This report provides a high level view of hardware and BIOS versions for systems that have used iPXE Anywhere. This can be useful for tracking such things as legacy BIOS systems during a migration to UEFI
If you have enabled the iPXE Anywhere Web Service for reporting and request handling then status reporting will be enabled as above and in addition all boot requests will be routed from 2PXE to the iPXE Anywhere Web Service. When it receives these Boot requests the iPXE Anywhere Web Service will execute the “RequestActionScript.ps1” PowerShell script. This script can be used to perform many custom actions during the boot process. During the workflow, control can be passed from the IPXE Anywhere Web Service to 2PXE and back again several times if required, making it a very powerful solution.
Please refer to the iPXE Anywhere Scripting Guide which contains examples and a full reference for scripting with both PowerShell and iPXE scripting.
Add (or remove) the system from Microsoft Configuration Manager Collections
Provide the logic required to update the BIOS if out of date
Switch from BIOS to UEFI
Auto-Create a ticket in your Service Desk of choice
Talk to any other management system
Syslog is a way for network devices to send event messages to a logging server – usually known as a Syslog server. The Syslog protocol is supported by a wide range of devices and can be used to log many different types of events. For example, a router might send messages about users logging on to console sessions, while a web-server may log Access-Denied events.
The iPXE Anywhere Web Service uses a built in SysLog server to retrieve syslog messages from the iPXE Network Boot Program.
StifleR is a powerful network Bandwidth Control and Reporting tool from 2Pint Software. The web service can be configured to feed progress data to StifleR to allow for early detection, visibility and reporting of client boot activity.
By allowing the StifleR service to retrieve messages, it can also provide the full error details directly to StifleR for troubleshooting.
The iPXE Anywhere Web Service can be configured to track your PXE Boot requests and progress. This can be useful in keeping track of all your PXE Boot attempts globally, tracking errors and failures, and tracing any errant activity. You can also view historical reports (management folks seem to like these stats), and of course create your own reports as it’s based on SSRS.
One of the most powerful features of the iPXE Anywhere Web Service is the ability to execute PowerShell code on the server in order to perform further, more complex actions on the system, or query other systems in your enterprise. Some examples:
Auto-create a support ticket on failed boot
Query an MDT Database for Computer details and eligibility before proceeding
Present a custom ‘Techie’ menu for troubleshooting
Check the system BIOS version and remediate if necessary
Order Pizza if it’s really late…(Seriously, it’s PowerShell so anything is possible right?!)
Start the installation by executing the correct installer (x64 for x64 systems). Ensure you have the License.cab available for the installer to access.
The Welcome dialog will appear:
After you click the Next button the EULA page appears. After you read through this and, assuming that you agree to all the terms of the EULA, click Next
Next you should see the Licensing dialog. Here you must supply the path to the license file for the installer to access.
Click on the “…” button and browse for the License.cab file.
Select a valid License.cab file and click ‘Open’
The path to the license file will now be updated and the ‘Next’ button will be available
Next, configure the account under which you would like the iPXE Anywhere service to run, either LocalSystem (recommended), or using a specific domain account. Note that if you are using a domain or local user account, the account must have the ‘Logon as a Service’ right and ideally the ability to create the SQL database (see “DataBase Creation Credentials” step below)
Next, you have the option to configure the Port over which the iPXE Anywhere Web Service will communicate with client computers.
The default is 8051.
You must Click the ‘Test Port’ button and assuming it works then click Next.
Next, select the SQL database server that will host the iPXE Anywhere Database. If you are running iPXE Anywhere on the local server, you can select (local). Otherwise, enter the server name and SQL instance Click next to continue.
The installer should then connect to that server and fill out the iPXEAnywhere Database name for you. Check this, and if it’s correct, click next to continue. Otherwise enter the correct name.
At this screen you must enter an account that will be used to create and update the iPXE Anywhere SQL Database at Service start up.
We recommend that you use the same account that you specified for the service, but you can choose a separate account if you wish. Don’t say we didn’t warn you..
You must then test the connection to verify that the account has the required security rights to access the SQL Server and create the database.
Next you can customize where you want to install the iPXE Anywhere service. Configure as required or accept the default and click Next.
You are now ready to unleash the iPXE Anywhere magic, so go ahead, click on Install button and then sit back and enjoy a cup of tea.
iPXE Anywhere is a powerful network booting solution.
2Pint Software took iPXE, a popular open source Network Boot firmware, and added the “Anywhere” functionality by providing a proxyDHCP/TFTP/HTTP server called 2PXE Server. Additional functionality and control can then be added through the addition of a Web Service component, called "iPXE Anywhere". These server components make iPXE sing and dance by allowing communication and control over the iPXE client software as well as providing reporting functionality.
This document covers the installation, configuration and usage of the iPXE Anywhere Web Service component, an optional add-on to the 2PXE Server.
iPXE Anywhere is a Web Service that the iPXE Network Boot Program can be configured to talk to through the 2PXE Server. The iPXE Anywhere server uses HTTP to talk with the clients and SQL to talk to the iPXE Anywhere SQL Database. It offers ‘extended functionality’ during the boot process such as BIOS updating, interacting with Microsoft MDT, creating custom iPXE menus etc.
This page contains documentation on how to manage script execution after logs are uploaded to server. This functionality came in the 2.9.20 release.
All uploads are done via BITS for efficient uploads across poor connections, allow for large payloads to be sent up without problems. BITS uploads support only one file, hence why we create a .zip file with key content to upload.
There are 2 types of uploads;
Uploads
Uploads with reply data
The script execution depends on the notification setting on the BITS upload directory. If you just want to have the logs, there is no need to have the script execution run. The script is triggered by the notification URL property defined on the BITS server. There are two types of notification:
There are two types of notification types;
Notification using file path - in this case the path of the uploaded file and the return file name is set as headers.
With the notification type 2, the entire uploaded file is then passed in the body of the request.
The iPXEAnywhere Web Service support both types of notification types via the following URLs:
The following is the flow of messages:
BITS Client uploads content to server
When the upload completes, the server side executes an HTTP call against the "notify" server URL specified in the BITS server components. This can be a local URL on the same server or a remote server. Whether this supports HTTPS or not, is unknow, documentation states that it cannot use TLS, but the examples shows use of TLS. Safe to assume the notification cannot use TLS and should therefore be local to the BITS server.
The iPXE Anywhere Web Service gets notified, via the notification call-back from the BITS server. This triggers the execution of a PowerShell script, which then gets the headers containing the full path to the uploaded file, and a path to a reply file. (Only used when the job is a Upload Reply job)
PowerShell script unpacks the payload, then triggers whatever action required.
PowerShell then writes the payload to the response file.
PowerShell exits and the Web Service returns either True or False. If False is returned, the iPXE Anywhere Web Service fails the incoming request and throws an exception, which in turn throws a 400 error to the BITS Client, failing the job. This leads to the BITSACP exit with a non zero exit code, returning the actual error code from BITS. Further information on the error message and context is written to the registry.
If True is returned, and the response file is created, the BITS server will instruct the BITS client to download the file specified.
The BITS client starts the download of the reply file.
The reply file name is written to registry, the file is available after the BITSACP exits. If the reply file download fails, the BITSACP exit code and context registry keys will reflect the HTTP error.
There are two types of uploads triggers;
Automatic, via the iPXEAnywhereWinPEClient.exe that runs after any task you want to monitor, we support PSD and ConfigMgr by default.
Manual, where the administrator specifies the uploads in a custom script or other types of execution via Task Sequence steps etc.
There are many ways to skin a client... some mentioned below.
Use several files into a compressed format. As an example the iPXE Client tries to collect the following data and compress into a .zu
Any log in the usual spot (Typically X:\Windows\Temp and all subfolders)
The complete set of Task Sequence Environment variables.
MSINFO32 data
Apart from the obvious file itself to upload, which we now know can be a .zip file of several files, you can also use the Filename itself. Instead of using file.bin you can use 10.10.137.14-CLI0002-P01-P01200005.ERROR or other really creative file names.
You can also set query parameters on the uploading URL after the file name itself. Like /file.zip?ComputerName=CLI0002&Network=10.10.11.30.
Both headers and query parameters are available when the PowerShell script executes on the server side.
There are some trivial ways to pass data;
Let the PowerShell script return $false, which will cause the notification call to error, and the BITS client retrieves a 400 error.
Use static/dynamic server response headers
Us an UploadReply job
An incomplete list of error codes can be found here: https://kb.2pintsoftware.com/help/bits-error-codes
Debug Logging is enabled through the iPXE Anywhere Service.exe.config file by changing the value of EnableDebugLog to “1”:
<add key="EnableDebugLog" value="1"/>
The actual log file itself is located in the directory listed under the DebugLogPath:
<add key="DebugLogPath" value="%PROGRAMDATA%\2Pint Software\iPXEWS\iPXEWS.log"/>
NOTE: Ensure that the service is stopped before running interactively
You can run the service directly from either a console or by double clicking the executable directly from Windows Explorer.. This starts the service in a command prompt window, allowing for simple troubleshooting as you can see the iPXE Anywhere workflow roll through the window.
When running in interactive mode all debug logging will be pushed to the console window. This helps greatly should you run into issues or when showcasing the technology. Please note that the console runs under the context of the executing user rather than the service account (SYSTEM by default) which can lead to access violations.
Sometimes, things can go a little pear shaped! If a machine is not booting as you would like it to, it’s likely that you have set a configuration that is invalid. Check the valid configuration options and if you can’t find the issue enable debug logging and send us the log after trying to boot an image. Please include any PowerShell scripts as well as the .config file in the email. Email the files to or use our online forums.
Note: Don’t forget to add all the files to a .zip folder otherwise the email might get caught in a spam filter.
