Skip to main content

How to Set Default Document for an IIS Website in Batch Script

When a user visits a URL that points to a directory rather than a specific file (e.g., http://example.com/ or http://example.com/about/), IIS checks its list of default documents to determine which file to serve. If a matching file is found in the directory, it is served automatically. If no match is found and directory browsing is disabled, the visitor receives a 403.14 - Forbidden error.

In this guide, we will explore how to configure the default document list for IIS websites using Batch Script and the appcmd.exe command-line tool.

Understanding Default Documents​

The default document list is an ordered collection of filenames. IIS checks each name in sequence and serves the first one that physically exists in the requested directory.

The default list on a fresh IIS installation typically includes:

  1. Default.htm
  2. Default.asp
  3. index.htm
  4. index.html
  5. iisstart.htm
  6. default.aspx

For modern web applications, you often need to customize this list, for example adding index.php for PHP sites or removing legacy entries like iisstart.htm.

Method 1: Adding a Default Document​

To add a new filename to the default document list:

@echo off
setlocal

set "appcmd=%SystemRoot%\System32\inetsrv\appcmd.exe"
set "site_name=MyWebsite"
set "doc_name=index.php"

:: Verify Admin
net session >nul 2>&1
if %errorlevel% neq 0 (
    echo [ERROR] Administrator privileges required.
    pause
    exit /b 1
)

echo Adding "%doc_name%" to default documents for "%site_name%"...

"%appcmd%" set config "%site_name%" /section:defaultDocument /+files.[value='%doc_name%']

if %errorlevel% equ 0 (
    echo [SUCCESS] "%doc_name%" added to default document list.
) else (
    echo [ERROR] Failed. The entry may already exist.
)

pause
endlocal

Inserting at a Specific Position​

By default, new entries are added at the end of the list. To insert at the beginning (position 0), use the @start directive:

"%appcmd%" set config "%site_name%" /section:defaultDocument /+files.[@start,value='index.php']

The @start directive places the new entry at the top, making it the first file IIS checks.

Method 2: Removing a Default Document​

To remove an entry that is no longer needed:

@echo off
setlocal

set "appcmd=%SystemRoot%\System32\inetsrv\appcmd.exe"
set "site_name=MyWebsite"
set "doc_name=iisstart.htm"

net session >nul 2>&1
if %errorlevel% neq 0 (
    echo [ERROR] Admin required.
    pause
    exit /b 1
)

echo Removing "%doc_name%" from default documents...

"%appcmd%" set config "%site_name%" /section:defaultDocument /-files.[value='%doc_name%']

if %errorlevel% equ 0 (
    echo [SUCCESS] "%doc_name%" removed.
) else (
    echo [ERROR] Entry not found or removal failed.
)

pause
endlocal

Method 3: Viewing the Current Default Document List​

@echo off
setlocal

set "appcmd=%SystemRoot%\System32\inetsrv\appcmd.exe"
set "site_name=MyWebsite"

net session >nul 2>&1
if %errorlevel% neq 0 (
    echo [ERROR] Admin required.
    pause
    exit /b 1
)

echo Default documents for "%site_name%":
echo =====================================
echo.

"%appcmd%" list config "%site_name%" /section:defaultDocument /text:*

pause
endlocal

This outputs each entry in the files collection, showing the evaluation order.

Method 4: Setting Up a Complete Default Document List​

For a clean configuration, you can clear the existing list and define exactly the documents you want, in the order you want.

@echo off
setlocal enabledelayedexpansion

set "appcmd=%SystemRoot%\System32\inetsrv\appcmd.exe"
set "site_name=ModernApp"

net session >nul 2>&1
if !errorlevel! neq 0 (
    echo [ERROR] Admin required.
    pause
    exit /b 1
)

echo Configuring default documents for "%site_name%"...
echo.

:: Clear existing entries (errors suppressed for entries that may not exist)
echo Removing old entries...
for %%D in (Default.htm Default.asp index.htm index.html iisstart.htm default.aspx) do (
    "%appcmd%" set config "%site_name%" /section:defaultDocument /-files.[value='%%D'] >nul 2>&1
)

:: Add desired entries in order (first added = last in list, so add in reverse priority)
echo Adding new entries...
set "add_failed=0"

"%appcmd%" set config "%site_name%" /section:defaultDocument /+files.[value='default.aspx'] >nul 2>&1
"%appcmd%" set config "%site_name%" /section:defaultDocument /+files.[value='index.php'] >nul 2>&1
"%appcmd%" set config "%site_name%" /section:defaultDocument /+files.[value='index.htm'] >nul 2>&1
"%appcmd%" set config "%site_name%" /section:defaultDocument /+files.[value='index.html'] >nul 2>&1

echo.
echo [SUCCESS] Default documents configured:
echo   1. index.html
echo   2. index.htm
echo   3. index.php
echo   4. default.aspx

:: Verify
echo.
echo Verification:
"%appcmd%" list config "%site_name%" /section:defaultDocument /text:*

pause
endlocal

Method 5: Enabling or Disabling the Default Document Feature​

You can completely enable or disable the default document feature. When disabled, even if index.html exists, navigating to the directory URL will not serve it automatically.

@echo off
setlocal

set "appcmd=%SystemRoot%\System32\inetsrv\appcmd.exe"
set "site_name=ApiService"

net session >nul 2>&1
if %errorlevel% neq 0 (
    echo [ERROR] Admin required.
    pause
    exit /b 1
)

:: Disable default document (useful for pure API endpoints)
"%appcmd%" set config "%site_name%" /section:defaultDocument /enabled:false

if %errorlevel% equ 0 (
    echo [OK] Default document feature disabled for "%site_name%".
    echo Requests to directory URLs will return 403 unless handled by application routing.
) else (
    echo [ERROR] Failed to disable default document feature.
)

pause
endlocal
info

Disabling default documents is common for API-only websites where all requests are handled by application routing (e.g., ASP.NET Web API, Node.js). There is no directory content to serve, and the default document check is unnecessary overhead.

Configuring at the Server Level​

To change the default document list for all websites on the server:

@echo off
setlocal

set "appcmd=%SystemRoot%\System32\inetsrv\appcmd.exe"

net session >nul 2>&1
if %errorlevel% neq 0 (
    echo [ERROR] Admin required.
    pause
    exit /b 1
)

:: Add index.php globally (affects all new and existing sites without local overrides)
"%appcmd%" set config /section:defaultDocument /+files.[value='index.php'] /commit:apphost

if %errorlevel% equ 0 (
    echo [OK] index.php added to global default documents.
) else (
    echo [ERROR] Failed. The entry may already exist at the server level.
)

pause
endlocal

Common Mistakes​

The Wrong Way: Adding Duplicate Entries​

:: WRONG - Running this twice creates an error on the second execution
"%appcmd%" set config "MySite" /section:defaultDocument /+files.[value='index.html']
"%appcmd%" set config "MySite" /section:defaultDocument /+files.[value='index.html']

Output Concern: appcmd will return an error on the second execution because the entry already exists. To make scripts idempotent, suppress the error with 2>nul or check for the entry's existence before adding.

The Wrong Way: Editing web.config Manually​

:: WRONG - Manually editing XML can introduce syntax errors
echo ^<defaultDocument enabled="true"^>^<files^>... >> web.config

The web.config file has strict XML formatting requirements. A malformed entry will cause the entire site to return HTTP 500 errors. Always use appcmd which validates the configuration before writing.

Best Practices​

  1. Remove unused entries: Clean up legacy defaults like iisstart.htm and Default.asp for a cleaner configuration.
  2. Order matters: Place the most commonly used document first to minimize file system lookups.
  3. Use appcmd for modifications: It validates XML before writing, preventing configuration corruption.
  4. Disable for API sites: Pure API endpoints do not need the default document module, and disabling it eliminates unnecessary file system checks per request.

Conclusion​

Configuring default documents for IIS websites from a Batch Script is handled by the appcmd set config command targeting the defaultDocument section. By adding, removing, and reordering entries in the default document collection, administrators can tailor IIS to serve the correct landing page for any type of web application, from traditional HTML sites to modern PHP and ASP.NET applications. Keeping the list clean and properly ordered ensures efficient request handling and a predictable user experience.

Table of Contents