Skip to content
This repository
Fetching contributors…

Cannot retrieve contributors at this time

file 3347 lines (2581 sloc) 130.179 kb
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 439 440 441 442 443 444 445 446 447 448 449 450 451 452 453 454 455 456 457 458 459 460 461 462 463 464 465 466 467 468 469 470 471 472 473 474 475 476 477 478 479 480 481 482 483 484 485 486 487 488 489 490 491 492 493 494 495 496 497 498 499 500 501 502 503 504 505 506 507 508 509 510 511 512 513 514 515 516 517 518 519 520 521 522 523 524 525 526 527 528 529 530 531 532 533 534 535 536 537 538 539 540 541 542 543 544 545 546 547 548 549 550 551 552 553 554 555 556 557 558 559 560 561 562 563 564 565 566 567 568 569 570 571 572 573 574 575 576 577 578 579 580 581 582 583 584 585 586 587 588 589 590 591 592 593 594 595 596 597 598 599 600 601 602 603 604 605 606 607 608 609 610 611 612 613 614 615 616 617 618 619 620 621 622 623 624 625 626 627 628 629 630 631 632 633 634 635 636 637 638 639 640 641 642 643 644 645 646 647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662 663 664 665 666 667 668 669 670 671 672 673 674 675 676 677 678 679 680 681 682 683 684 685 686 687 688 689 690 691 692 693 694 695 696 697 698 699 700 701 702 703 704 705 706 707 708 709 710 711 712 713 714 715 716 717 718 719 720 721 722 723 724 725 726 727 728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768 769 770 771 772 773 774 775 776 777 778 779 780 781 782 783 784 785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813 814 815 816 817 818 819 820 821 822 823 824 825 826 827 828 829 830 831 832 833 834 835 836 837 838 839 840 841 842 843 844 845 846 847 848 849 850 851 852 853 854 855 856 857 858 859 860 861 862 863 864 865 866 867 868 869 870 871 872 873 874 875 876 877 878 879 880 881 882 883 884 885 886 887 888 889 890 891 892 893 894 895 896 897 898 899 900 901 902 903 904 905 906 907 908 909 910 911 912 913 914 915 916 917 918 919 920 921 922 923 924 925 926 927 928 929 930 931 932 933 934 935 936 937 938 939 940 941 942 943 944 945 946 947 948 949 950 951 952 953 954 955 956 957 958 959 960 961 962 963 964 965 966 967 968 969 970 971 972 973 974 975 976 977 978 979 980 981 982 983 984 985 986 987 988 989 990 991 992 993 994 995 996 997 998 999 1000 1001 1002 1003 1004 1005 1006 1007 1008 1009 1010 1011 1012 1013 1014 1015 1016 1017 1018 1019 1020 1021 1022 1023 1024 1025 1026 1027 1028 1029 1030 1031 1032 1033 1034 1035 1036 1037 1038 1039 1040 1041 1042 1043 1044 1045 1046 1047 1048 1049 1050 1051 1052 1053 1054 1055 1056 1057 1058 1059 1060 1061 1062 1063 1064 1065 1066 1067 1068 1069 1070 1071 1072 1073 1074 1075 1076 1077 1078 1079 1080 1081 1082 1083 1084 1085 1086 1087 1088 1089 1090 1091 1092 1093 1094 1095 1096 1097 1098 1099 1100 1101 1102 1103 1104 1105 1106 1107 1108 1109 1110 1111 1112 1113 1114 1115 1116 1117 1118 1119 1120 1121 1122 1123 1124 1125 1126 1127 1128 1129 1130 1131 1132 1133 1134 1135 1136 1137 1138 1139 1140 1141 1142 1143 1144 1145 1146 1147 1148 1149 1150 1151 1152 1153 1154 1155 1156 1157 1158 1159 1160 1161 1162 1163 1164 1165 1166 1167 1168 1169 1170 1171 1172 1173 1174 1175 1176 1177 1178 1179 1180 1181 1182 1183 1184 1185 1186 1187 1188 1189 1190 1191 1192 1193 1194 1195 1196 1197 1198 1199 1200 1201 1202 1203 1204 1205 1206 1207 1208 1209 1210 1211 1212 1213 1214 1215 1216 1217 1218 1219 1220 1221 1222 1223 1224 1225 1226 1227 1228 1229 1230 1231 1232 1233 1234 1235 1236 1237 1238 1239 1240 1241 1242 1243 1244 1245 1246 1247 1248 1249 1250 1251 1252 1253 1254 1255 1256 1257 1258 1259 1260 1261 1262 1263 1264 1265 1266 1267 1268 1269 1270 1271 1272 1273 1274 1275 1276 1277 1278 1279 1280 1281 1282 1283 1284 1285 1286 1287 1288 1289 1290 1291 1292 1293 1294 1295 1296 1297 1298 1299 1300 1301 1302 1303 1304 1305 1306 1307 1308 1309 1310 1311 1312 1313 1314 1315 1316 1317 1318 1319 1320 1321 1322 1323 1324 1325 1326 1327 1328 1329 1330 1331 1332 1333 1334 1335 1336 1337 1338 1339 1340 1341 1342 1343 1344 1345 1346 1347 1348 1349 1350 1351 1352 1353 1354 1355 1356 1357 1358 1359 1360 1361 1362 1363 1364 1365 1366 1367 1368 1369 1370 1371 1372 1373 1374 1375 1376 1377 1378 1379 1380 1381 1382 1383 1384 1385 1386 1387 1388 1389 1390 1391 1392 1393 1394 1395 1396 1397 1398 1399 1400 1401 1402 1403 1404 1405 1406 1407 1408 1409 1410 1411 1412 1413 1414 1415 1416 1417 1418 1419 1420 1421 1422 1423 1424 1425 1426 1427 1428 1429 1430 1431 1432 1433 1434 1435 1436 1437 1438 1439 1440 1441 1442 1443 1444 1445 1446 1447 1448 1449 1450 1451 1452 1453 1454 1455 1456 1457 1458 1459 1460 1461 1462 1463 1464 1465 1466 1467 1468 1469 1470 1471 1472 1473 1474 1475 1476 1477 1478 1479 1480 1481 1482 1483 1484 1485 1486 1487 1488 1489 1490 1491 1492 1493 1494 1495 1496 1497 1498 1499 1500 1501 1502 1503 1504 1505 1506 1507 1508 1509 1510 1511 1512 1513 1514 1515 1516 1517 1518 1519 1520 1521 1522 1523 1524 1525 1526 1527 1528 1529 1530 1531 1532 1533 1534 1535 1536 1537 1538 1539 1540 1541 1542 1543 1544 1545 1546 1547 1548 1549 1550 1551 1552 1553 1554 1555 1556 1557 1558 1559 1560 1561 1562 1563 1564 1565 1566 1567 1568 1569 1570 1571 1572 1573 1574 1575 1576 1577 1578 1579 1580 1581 1582 1583 1584 1585 1586 1587 1588 1589 1590 1591 1592 1593 1594 1595 1596 1597 1598 1599 1600 1601 1602 1603 1604 1605 1606 1607 1608 1609 1610 1611 1612 1613 1614 1615 1616 1617 1618 1619 1620 1621 1622 1623 1624 1625 1626 1627 1628 1629 1630 1631 1632 1633 1634 1635 1636 1637 1638 1639 1640 1641 1642 1643 1644 1645 1646 1647 1648 1649 1650 1651 1652 1653 1654 1655 1656 1657 1658 1659 1660 1661 1662 1663 1664 1665 1666 1667 1668 1669 1670 1671 1672 1673 1674 1675 1676 1677 1678 1679 1680 1681 1682 1683 1684 1685 1686 1687 1688 1689 1690 1691 1692 1693 1694 1695 1696 1697 1698 1699 1700 1701 1702 1703 1704 1705 1706 1707 1708 1709 1710 1711 1712 1713 1714 1715 1716 1717 1718 1719 1720 1721 1722 1723 1724 1725 1726 1727 1728 1729 1730 1731 1732 1733 1734 1735 1736 1737 1738 1739 1740 1741 1742 1743 1744 1745 1746 1747 1748 1749 1750 1751 1752 1753 1754 1755 1756 1757 1758 1759 1760 1761 1762 1763 1764 1765 1766 1767 1768 1769 1770 1771 1772 1773 1774 1775 1776 1777 1778 1779 1780 1781 1782 1783 1784 1785 1786 1787 1788 1789 1790 1791 1792 1793 1794 1795 1796 1797 1798 1799 1800 1801 1802 1803 1804 1805 1806 1807 1808 1809 1810 1811 1812 1813 1814 1815 1816 1817 1818 1819 1820 1821 1822 1823 1824 1825 1826 1827 1828 1829 1830 1831 1832 1833 1834 1835 1836 1837 1838 1839 1840 1841 1842 1843 1844 1845 1846 1847 1848 1849 1850 1851 1852 1853 1854 1855 1856 1857 1858 1859 1860 1861 1862 1863 1864 1865 1866 1867 1868 1869 1870 1871 1872 1873 1874 1875 1876 1877 1878 1879 1880 1881 1882 1883 1884 1885 1886 1887 1888 1889 1890 1891 1892 1893 1894 1895 1896 1897 1898 1899 1900 1901 1902 1903 1904 1905 1906 1907 1908 1909 1910 1911 1912 1913 1914 1915 1916 1917 1918 1919 1920 1921 1922 1923 1924 1925 1926 1927 1928 1929 1930 1931 1932 1933 1934 1935 1936 1937 1938 1939 1940 1941 1942 1943 1944 1945 1946 1947 1948 1949 1950 1951 1952 1953 1954 1955 1956 1957 1958 1959 1960 1961 1962 1963 1964 1965 1966 1967 1968 1969 1970 1971 1972 1973 1974 1975 1976 1977 1978 1979 1980 1981 1982 1983 1984 1985 1986 1987 1988 1989 1990 1991 1992 1993 1994 1995 1996 1997 1998 1999 2000 2001 2002 2003 2004 2005 2006 2007 2008 2009 2010 2011 2012 2013 2014 2015 2016 2017 2018 2019 2020 2021 2022 2023 2024 2025 2026 2027 2028 2029 2030 2031 2032 2033 2034 2035 2036 2037 2038 2039 2040 2041 2042 2043 2044 2045 2046 2047 2048 2049 2050 2051 2052 2053 2054 2055 2056 2057 2058 2059 2060 2061 2062 2063 2064 2065 2066 2067 2068 2069 2070 2071 2072 2073 2074 2075 2076 2077 2078 2079 2080 2081 2082 2083 2084 2085 2086 2087 2088 2089 2090 2091 2092 2093 2094 2095 2096 2097 2098 2099 2100 2101 2102 2103 2104 2105 2106 2107 2108 2109 2110 2111 2112 2113 2114 2115 2116 2117 2118 2119 2120 2121 2122 2123 2124 2125 2126 2127 2128 2129 2130 2131 2132 2133 2134 2135 2136 2137 2138 2139 2140 2141 2142 2143 2144 2145 2146 2147 2148 2149 2150 2151 2152 2153 2154 2155 2156 2157 2158 2159 2160 2161 2162 2163 2164 2165 2166 2167 2168 2169 2170 2171 2172 2173 2174 2175 2176 2177 2178 2179 2180 2181 2182 2183 2184 2185 2186 2187 2188 2189 2190 2191 2192 2193 2194 2195 2196 2197 2198 2199 2200 2201 2202 2203 2204 2205 2206 2207 2208 2209 2210 2211 2212 2213 2214 2215 2216 2217 2218 2219 2220 2221 2222 2223 2224 2225 2226 2227 2228 2229 2230 2231 2232 2233 2234 2235 2236 2237 2238 2239 2240 2241 2242 2243 2244 2245 2246 2247 2248 2249 2250 2251 2252 2253 2254 2255 2256 2257 2258 2259 2260 2261 2262 2263 2264 2265 2266 2267 2268 2269 2270 2271 2272 2273 2274 2275 2276 2277 2278 2279 2280 2281 2282 2283 2284 2285 2286 2287 2288 2289 2290 2291 2292 2293 2294 2295 2296 2297 2298 2299 2300 2301 2302 2303 2304 2305 2306 2307 2308 2309 2310 2311 2312 2313 2314 2315 2316 2317 2318 2319 2320 2321 2322 2323 2324 2325 2326 2327 2328 2329 2330 2331 2332 2333 2334 2335 2336 2337 2338 2339 2340 2341 2342 2343 2344 2345 2346 2347 2348 2349 2350 2351 2352 2353 2354 2355 2356 2357 2358 2359 2360 2361 2362 2363 2364 2365 2366 2367 2368 2369 2370 2371 2372 2373 2374 2375 2376 2377 2378 2379 2380 2381 2382 2383 2384 2385 2386 2387 2388 2389 2390 2391 2392 2393 2394 2395 2396 2397 2398 2399 2400 2401 2402 2403 2404 2405 2406 2407 2408 2409 2410 2411 2412 2413 2414 2415 2416 2417 2418 2419 2420 2421 2422 2423 2424 2425 2426 2427 2428 2429 2430 2431 2432 2433 2434 2435 2436 2437 2438 2439 2440 2441 2442 2443 2444 2445 2446 2447 2448 2449 2450 2451 2452 2453 2454 2455 2456 2457 2458 2459 2460 2461 2462 2463 2464 2465 2466 2467 2468 2469 2470 2471 2472 2473 2474 2475 2476 2477 2478 2479 2480 2481 2482 2483 2484 2485 2486 2487 2488 2489 2490 2491 2492 2493 2494 2495 2496 2497 2498 2499 2500 2501 2502 2503 2504 2505 2506 2507 2508 2509 2510 2511 2512 2513 2514 2515 2516 2517 2518 2519 2520 2521 2522 2523 2524 2525 2526 2527 2528 2529 2530 2531 2532 2533 2534 2535 2536 2537 2538 2539 2540 2541 2542 2543 2544 2545 2546 2547 2548 2549 2550 2551 2552 2553 2554 2555 2556 2557 2558 2559 2560 2561 2562 2563 2564 2565 2566 2567 2568 2569 2570 2571 2572 2573 2574 2575 2576 2577 2578 2579 2580 2581 2582 2583 2584 2585 2586 2587 2588 2589 2590 2591 2592 2593 2594 2595 2596 2597 2598 2599 2600 2601 2602 2603 2604 2605 2606 2607 2608 2609 2610 2611 2612 2613 2614 2615 2616 2617 2618 2619 2620 2621 2622 2623 2624 2625 2626 2627 2628 2629 2630 2631 2632 2633 2634 2635 2636 2637 2638 2639 2640 2641 2642 2643 2644 2645 2646 2647 2648 2649 2650 2651 2652 2653 2654 2655 2656 2657 2658 2659 2660 2661 2662 2663 2664 2665 2666 2667 2668 2669 2670 2671 2672 2673 2674 2675 2676 2677 2678 2679 2680 2681 2682 2683 2684 2685 2686 2687 2688 2689 2690 2691 2692 2693 2694 2695 2696 2697 2698 2699 2700 2701 2702 2703 2704 2705 2706 2707 2708 2709 2710 2711 2712 2713 2714 2715 2716 2717 2718 2719 2720 2721 2722 2723 2724 2725 2726 2727 2728 2729 2730 2731 2732 2733 2734 2735 2736 2737 2738 2739 2740 2741 2742 2743 2744 2745 2746 2747 2748 2749 2750 2751 2752 2753 2754 2755 2756 2757 2758 2759 2760 2761 2762 2763 2764 2765 2766 2767 2768 2769 2770 2771 2772 2773 2774 2775 2776 2777 2778 2779 2780 2781 2782 2783 2784 2785 2786 2787 2788 2789 2790 2791 2792 2793 2794 2795 2796 2797 2798 2799 2800 2801 2802 2803 2804 2805 2806 2807 2808 2809 2810 2811 2812 2813 2814 2815 2816 2817 2818 2819 2820 2821 2822 2823 2824 2825 2826 2827 2828 2829 2830 2831 2832 2833 2834 2835 2836 2837 2838 2839 2840 2841 2842 2843 2844 2845 2846 2847 2848 2849 2850 2851 2852 2853 2854 2855 2856 2857 2858 2859 2860 2861 2862 2863 2864 2865 2866 2867 2868 2869 2870 2871 2872 2873 2874 2875 2876 2877 2878 2879 2880 2881 2882 2883 2884 2885 2886 2887 2888 2889 2890 2891 2892 2893 2894 2895 2896 2897 2898 2899 2900 2901 2902 2903 2904 2905 2906 2907 2908 2909 2910 2911 2912 2913 2914 2915 2916 2917 2918 2919 2920 2921 2922 2923 2924 2925 2926 2927 2928 2929 2930 2931 2932 2933 2934 2935 2936 2937 2938 2939 2940 2941 2942 2943 2944 2945 2946 2947 2948 2949 2950 2951 2952 2953 2954 2955 2956 2957 2958 2959 2960 2961 2962 2963 2964 2965 2966 2967 2968 2969 2970 2971 2972 2973 2974 2975 2976 2977 2978 2979 2980 2981 2982 2983 2984 2985 2986 2987 2988 2989 2990 2991 2992 2993 2994 2995 2996 2997 2998 2999 3000 3001 3002 3003 3004 3005 3006 3007 3008 3009 3010 3011 3012 3013 3014 3015 3016 3017 3018 3019 3020 3021 3022 3023 3024 3025 3026 3027 3028 3029 3030 3031 3032 3033 3034 3035 3036 3037 3038 3039 3040 3041 3042 3043 3044 3045 3046 3047 3048 3049 3050 3051 3052 3053 3054 3055 3056 3057 3058 3059 3060 3061 3062 3063 3064 3065 3066 3067 3068 3069 3070 3071 3072 3073 3074 3075 3076 3077 3078 3079 3080 3081 3082 3083 3084 3085 3086 3087 3088 3089 3090 3091 3092 3093 3094 3095 3096 3097 3098 3099 3100 3101 3102 3103 3104 3105 3106 3107 3108 3109 3110 3111 3112 3113 3114 3115 3116 3117 3118 3119 3120 3121 3122 3123 3124 3125 3126 3127 3128 3129 3130 3131 3132 3133 3134 3135 3136 3137 3138 3139 3140 3141 3142 3143 3144 3145 3146 3147 3148 3149 3150 3151 3152 3153 3154 3155 3156 3157 3158 3159 3160 3161 3162 3163 3164 3165 3166 3167 3168 3169 3170 3171 3172 3173 3174 3175 3176 3177 3178 3179 3180 3181 3182 3183 3184 3185 3186 3187 3188 3189 3190 3191 3192 3193 3194 3195 3196 3197 3198 3199 3200 3201 3202 3203 3204 3205 3206 3207 3208 3209 3210 3211 3212 3213 3214 3215 3216 3217 3218 3219 3220 3221 3222 3223 3224 3225 3226 3227 3228 3229 3230 3231 3232 3233 3234 3235 3236 3237 3238 3239 3240 3241 3242 3243 3244 3245 3246 3247 3248 3249 3250 3251 3252 3253 3254 3255 3256 3257 3258 3259 3260 3261 3262 3263 3264 3265 3266 3267 3268 3269 3270 3271 3272 3273 3274 3275 3276 3277 3278 3279 3280 3281 3282 3283 3284 3285 3286 3287 3288 3289 3290 3291 3292 3293 3294 3295 3296 3297 3298 3299 3300 3301 3302 3303 3304 3305 3306 3307 3308 3309 3310 3311 3312 3313 3314 3315 3316 3317 3318 3319 3320 3321 3322 3323 3324 3325 3326 3327 3328 3329 3330 3331 3332 3333 3334 3335 3336 3337 3338 3339 3340 3341 3342 3343 3344 3345 3346 3347
\documentclass[11pt,oneside,english]{book}

\usepackage{ifpdf}

\ifpdf
  \usepackage[pdftex]{graphicx}
  \pdfcompresslevel=9
  \DeclareGraphicsExtensions{.png,.jpg,.pdf,.mps}
\else
  \usepackage{graphicx}
  \DeclareGraphicsExtensions{.ps,.eps}
\fi
\usepackage[T1]{fontenc}
\usepackage[latin1]{inputenc}
\usepackage{geometry}
\geometry{verbose,letterpaper,tmargin=1in,bmargin=1in,lmargin=1in,rmargin=1in}
\usepackage{babel}
\setcounter{secnumdepth}{3}
\setlength\parskip{\medskipamount}
\setlength\parindent{0pt}
\usepackage{url}
\usepackage{pslatex}
\usepackage[colorlinks=false]{hyperref}

\newcommand{\Erlang} % Write Erlang correctly
        {{\sc Erlang}}


\newcommand{\Yaws} % Write Yaws correctly
        {{\sc Yaws}}


\makeatletter

\usepackage[T1]{fontenc}
\usepackage{xspace}
\usepackage{html}

\makeatother
\begin{document}



\title{Yaws - Yet Another Web Server}


\author{Claes Wikstrom\\
klacke@hyber.org}





\maketitle
\tableofcontents{}



\chapter{Introduction}


\begin{figure}[h]
\begin{center}

 \includegraphics[scale=0.6] {yaws_head}

\end{center}
\end{figure}

\Yaws\ is an \Erlang\ web server. It's written in \Erlang\ and it uses
\Erlang\ as its embedded language similar to PHP in Apache or Java in Tomcat.

The advantages of \Erlang\ as an embedded web page language as opposed to
Java or PHP are many.
\begin{itemize}

\item{Speed - Using \Erlang\ for both implementing the web server itself as well
as embedded script language gives excellent dynamic page generation
performance.}

\item{Beauty - Well this is subjective}

\item{Scalability - due to the lightweight processes of \Erlang{}, \Yaws\
is able to handle a very large number of concurrent connections}

\end{itemize}

\Yaws\ has a wide feature set; it supports:

\begin{itemize}
\item HTTP 1.0 and HTTP 1.1
\item Static content page delivery
\item Dynamic content generation using embedded \Erlang\ code in the
HTML pages
\item Common Log Format traffic logs
\item Virtual hosting with several servers on the same IP address
\item Multiple servers on multiple IP addresses
\item HTTP tracing for debugging
\item An interactive interpreter environment in the Web server for use while
developing and debugging a web site
\item RAM caching of commonly accessed pages
\item Full streaming capabilities of both upload and download of dynamically
generated pages
\item SSL
\item Support for WWW-Authenticated pages
\item Support API for cookie based sessions
\item Application Modules where virtual directory hierarchies can
be made
\item Embedded mode
\item WebSockets (RFC 6455)
\item Long polling (COMET) applications
\item Forward and reverse proxying
\end{itemize}

\section{Prerequisites}
This document requires that the reader:
\begin{itemize}
\item Is well acquainted with the \Erlang\ programming language.
\item Understands basic Web technologies.
\end{itemize}


\section{A tiny example}

We introduce \Yaws\ by help of a tiny example.
 The web server \Yaws\ serves and delivers
static content pages similar to any old web server, except that \Yaws\ does this
much faster than most web servers. It's the dynamic pages
that makes \Yaws\ interesting. Any page with the suffix ``.yaws'' is considered
a dynamic \Yaws\ page. A \Yaws\ page can contain embedded \Erlang\ snippets that
are executed while the page is being delivered to the WWW browser.

Example 1.1 is the HTML code for a small \Yaws\ page.


\begin{figure}[h]
\begin{verbatim}
<html>

<p> First paragraph

<erl>
out(Arg) ->
    {html, "<p>This string gets inserted into HTML document dynamically"}.
</erl>

<p> And here is some more HTML code

</html>
\end{verbatim}
\caption{Example 1.1}
\end{figure}

It illustrates the basic idea behind \Yaws{}. The HTML code, generally
stored in a file ending with a ``.yaws'' suffix, can contain
\verb+<erl>+ and \verb+</erl>+ tags and inside these tags an
\Erlang\ function called \verb+out/1+ gets called and the output of
that function is inserted into the HTML document, dynamically.

It is possible to have several chunks of HTML code together with several
chunks of \Erlang\ code in the same \Yaws\ page.

The \verb+Arg+ argument supplied to the automatically invoked \verb+out/1+
function is an \Erlang\ record that contains various data which is interesting
when generating dynamic pages. For example the HTTP headers which were sent
from the WWW client, the actual TCP/IP socket leading to the WWW client.
This will be elaborated on thoroughly in later chapters.

The \verb+out/1+ function returned the tuple \verb+{html, String}+ and
\verb+String+ gets inserted into the HTML output. There are number
of different return values that can be returned from the \verb+out/1+ function
in order to control the behavior and output from the \Yaws\ web server.


\chapter{Compile, Install, Config and Run}

This chapter is more of a ``Getting started'' guide than a full
description of the \Yaws\ configuration. \Yaws\ is hosted on Github
at \url{ https://github.com/klacke/yaws }. This is where the source
code resides in a git repository and the latest unreleased version is
available via git through the following commands:

\begin{verbatim}

$ git clone https://github.com/klacke/yaws

\end{verbatim}

Released version of \Yaws\ are available at
\url{http://yaws.hyber.org/download}.

\subsection{Compile and Install}

To compile and install a \Yaws\ release
one of the prerequisites is a properly installed \Erlang\ system. \Yaws\
runs on \Erlang\ releases OTP R8 and later. Get \Erlang\ from
\url{http://www.erlang.org/}

Compile and install is straight forward:
\begin{verbatim}
# cd /usr/local/src
# tar xfz yaws-X.XX.tar.gz
# cd yaws
# ./configure && make
# make install
\end{verbatim}

The \verb+make+ command will compile the \Yaws\ web server with the
\verb+erlc+ compiler found by the configure script.

\begin{itemize}

\item \verb+make install+ - will install the executable called
\verb+yaws+ in \verb+/usr/local/bin/+ and a working
configuration file in \verb+/etc/yaws.conf+

\item \verb+make local_install+ - will install the executable in
\verb+$HOME/bin+ and a working configuration file in
         \verb+$HOME/yaws.conf+

\end{itemize}

While developing a \Yaws\ site, it's typically most convenient to
use the local\_install and run \Yaws\ as a non-privileged user.


\subsection{Configure}
Let's take a look at the config file that gets written to \$HOME after
a local\_install.


\begin{figure}[h]
\begin{verbatim}

# first we have a set of globals

logdir = .
ebin_dir = /home/klacke/yaws/yaws/examples/ebin
include_dir = /home/klacke/yaws/yaws/examples/include

# and then a set of servers

<server localhost>
port = 8000
listen = 127.0.0.1
docroot = /home/klacke/yaws/yaws/scripts/../www
</server>


\end{verbatim}
\caption{Minimal Local Configuration}
\end{figure}

The configuration consists of an initial set of global
variables that are valid for all defined servers.

The only global directive we need to care about for now is the logdir.
\Yaws\ produces a number of log files and they will---using the
Configuration from Figure 2.1---end up in the current working
directory. We start \Yaws\ interactively as

\begin{verbatim}
# ~/bin/yaws -i
Erlang (BEAM) emulator version 5.1.2.b2 [source]

Eshell V5.1.2.b2 (abort with ^G)
1>
=INFO REPORT==== 30-Oct-2002::01:38:22 ===
Using config file /home/klacke/yaws.conf
=INFO REPORT==== 30-Oct-2002::01:38:22 ===
Listening to 127.0.0.1:8000 for servers ["localhost:8000"]

1>
\end{verbatim}

By starting \Yaws\ in interactive mode (using the command switch
\textit{-i}) we get a regular \Erlang\ prompt. This is most convenient
when developing \Yaws\ pages. For example we:

\begin{itemize}
\item{Can dynamically compile and load optional helper modules we need.}
\item{Get all the crash and error reports written directly to the
terminal.}
\end{itemize}

The configuration in Example 2.1 defined one HTTP server on address
127.0.0.1:8000 called "localhost". It is important to understand the
difference between the name and the address of a server. The name is
the expected value in the client HTTP \verb+Host:+ header. That is
typically the same as the fully-qualified DNS name of the server
whereas the address is the actual IP address of the server.

Since \Yaws\ support virtual hosting with several servers on the same
IP address, this matters.

Nevertheless, our server listens to \textit{127.0.0.1:8000} and
has the name "localhost", thus the correct URL for this server
is \verb+http://localhost:8000+.

The document root (docroot) for the server is set to the \verb+www+
directory in the \Yaws\ source code distribution. This directory
contains a bunch of examples and we should be able to run all those
example now on the URL \verb+http://localhost:8000+.

Instead of editing and adding files in the \Yaws\ \verb+www+
directory, we create yet another server on the same IP address but a
different port number --- and in particular a different document root
where we can add our own files.

\begin{verbatim}
# mkdir ~/test
# mkdir ~/test/logs
\end{verbatim}

Now change the config so it looks like this:

\begin{verbatim}

logdir = /home/klacke/test/logs
ebin_dir = /home/klacke/test
include_dir = /home/klacke/test

<server localhost>
port = 8000
listen = 127.0.0.1
docroot = /home/klacke/yaws/yaws/www
</server>

<server localhost>
port = 8001
listen = 127.0.0.1
docroot = /home/klacke/test
</server>


\end{verbatim}

We define two servers, one being the original default
and a new pointing to a document root in our home directory.

We can now start to add static content in the form of HTML pages,
dynamic content in the form of \verb+.yaws+ pages or
\Erlang\ \verb+.beam+ code that can be used to generate the dynamic
content.

The load path will be set so that beam code in the directory
\char`\~\verb+/test+ will be automatically loaded when referenced.

It is best to run \Yaws\ interactively while developing the site.
In order to start the \Yaws\ as a daemon, we give the flags:
\begin{verbatim}
# yaws -D --heart
\end{verbatim}

The \textit{-D} or \textit{--daemon} flags instructs \Yaws\ to run as
a daemon and the \textit{--heart} flag will start a heartbeat program
called heart which restarts the daemon if it should crash or if it
stops responding to a regular heartbeat. By default, heart will
restart the daemon unless it has already restarted 5 times in 60
seconds or less, in which case it considers the situation fatal and
refuses to restart the daemon again. The \textit{-heart-restart=C,T}
flag changes the default 5 restarts in 60 seconds to \textit{C}
restarts in \textit{T} seconds. For infinite restarts, set both
\textit{C} and \textit{T} to 0. This flag also enables the
\textit{--heart} flag.

Once started in daemon mode, we have very limited ways of interacting
with the daemon. It is possible to query the daemon using:
\begin{verbatim}
# yaws -S
\end{verbatim}

This command produces a simple printout of uptime and number of hits
for each configured server.

If we change the configuration, we can HUP the daemon using the
command:
\begin{verbatim}
# yaws -h
\end{verbatim}

This will force the daemon to reread the configuration file.



\chapter{Static content}

\Yaws\ acts very much like any regular web server while delivering
static pages. By default \Yaws\ will cache static content in RAM.
The caching behavior is controlled by a number of global
configuration directives. Since the RAM caching occupies memory,
it may be interesting to tweak the default values for the caching directives
or even to turn it off completely.

The following configuration directives control the caching behavior
\begin{itemize}
\item \textit{max\_num\_cached\_files = Integer}

\Yaws\ will cache small files such as commonly
accessed GIF images in RAM. This directive sets a
maximum number on the number of cached files. The
default value is 400.

\item\textit{max\_num\_cached\_bytes = Integer}

This directive controls the total amount of RAM
which can maximally be used for cached RAM files.
The default value is 1000000, 1 megabyte.


\item\textit{max\_size\_cached\_file = Integer}

This directive sets a maximum size on the files
that are RAM cached by \Yaws{}. The default value is
8000 bytes, 8 batters.



\end{itemize}

It may be considered to be confusing, but the numbers specified
in the above mentioned cache directives are local to each
server. Thus if we have specified \verb+max_num_cached_bytes = 1000000+
and have defined 3 servers, we may actually use $3 * 1000000$ bytes.




\chapter{Dynamic content}

Dynamic content is what \Yaws\ is all about. Most web servers are
designed with HTTP and static content in mind whereas \Yaws\ is
designed for dynamic pages from the start. Most large sites on the
Web today make heavy use of dynamic pages.


\section{Introduction}

When the client \verb+GET+s a page that has a ``.yaws'' suffix, the
\Yaws\ server will read that page from the hard disk and divide it in
parts that consist of HTML code and \Erlang\ code. Each chunk of
\Erlang\ code will be compiled into a module. The chunk of
\Erlang\ code must contain a function \verb+out/1+. If it doesn't the
\Yaws\ server will insert a proper error message into the generated
HTML output.

When the \Yaws\ server ships a \verb+.yaws+ page it will process it
chunk by chunk through the \verb+.yaws+ file. If it is HTML code, the
server will ship that as is, whereas if it is \Erlang\ code, the
\Yaws\ server will invoke the \verb+out/1+ function in that code and
insert the output of that \verb+out/1+ function into the stream of
HTML that is being shipped to the client.

\Yaws\ will (of course) cache the result of the compilation and the
next time a client requests the same \verb+.yaws+ page \Yaws\ will be
able to invoke the already-compiled modules directly.


\section{EHTML}

There are two ways to make the \verb+out/1+ function generate HTML
output. The first and most easy to understand is by returning a tuple
\verb+{html, String}+ where \verb+String+ then is regular HTML data
(possibly as a deep list of strings and/or binaries) which will simply
be inserted into the output stream.
An example:

\begin{verbatim}
<html>
<h1> Example 1 </h1>

<erl>
out(A) ->
Headers = A#arg.headers,
{html, io_lib:format("You say that you're running ~p",
[Headers#headers.user_agent])}.

</erl>

</html>

\end{verbatim}


The second way to generate output is by returning a tuple
\verb+{ehtml, EHTML}+. The term \verb+EHTML+ must adhere to the
following structure:

$EHTML = [EHTML] | \{TAG, Attrs, Body\} |
               \{TAG, Attrs\} | \{TAG\} |\\*
\hspace*{0.75 in} \{Module, Fun, [Args]\} | fun/0 |\\*
\hspace*{0.75 in} binary() | character()$

$TAG = atom()$

$Attrs = [\{HtmlAttribute, Value\}]$

$HtmlAttribute = atom()$

$Value = string() | atom() |
         \{Module, Fun, [Args]\} | fun/0$

$Body = EHTML$

We give an example to show what we mean. The tuple

\begin{verbatim}
{ehtml, {table, [{bgcolor, grey}],
[
{tr, [],
[
{td, [], "1"},
{td, [], "2"},
{td, [], "3"}
]
},
{tr, [],
[{td, [{colspan, "3"}], "444"}]}]}}.
\end{verbatim}

expands into the following HTML code:

\begin{verbatim}
<table bgcolor="grey">
<tr>
<td> 1 </td
<td> 2 </td>
<td> 3 </td>
</tr>
<tr>
<td colspan="3"> 444 </td>
</tr>
</table>

\end{verbatim}

At a first glance it may appears as if the HTML code is more beautiful
than the \Erlang\ tuple. That may very well be the case from a purely
aesthetic point of view. However the \Erlang\ code has the advantage
of being perfectly indented by editors that have syntax support for
\Erlang\ (read Emacs). Furthermore, the \Erlang\ code is easier to
manipulate from an \Erlang\ program.

Note that ehtml supports function calls as values. Functions can
return any legal ehtml value, including other function
values. \Yaws\ supports \verb+{M,F,[Args]}+ and \verb+fun/0+ function
value forms.

As an example of some more interesting ehtml we could have an
\verb+out/1+ function that prints some of the HTTP headers. In the
\verb+www+ directory of the \Yaws\ source code distribution we have a
file called \verb+arg.yaws+. The file demonstrates the \verb+Arg+
\verb+#arg+ record parameter which is passed to the \verb+out/1+
function.

But before we discuss that code, we describe the \verb+Arg+ record
in detail.

Here is the \verb+yaws_api.hrl+ file which is in included by default
in all \Yaws\ files. The \verb+#arg{}+ record contains many fields
that are useful when processing HTTP request dynamically. We have
access to basically all the information associated with the client
request such as:

\begin{itemize}

\item The actual socket leading back to the HTTP client
\item All the HTTP headers -- parsed into a \verb+#headers+ record
\item The HTTP request -- parsed into a \verb+#http_request+ record
\item \verb+clidata+ -- data which is \verb+POST+ed by the client
\item \verb+querydata+ -- this is the remainder of the URL following
the first occurrence of a '?' character, if any.
\item \verb+docroot+ -- the absolute path to the docroot of the
virtual server that is processing the request.
\end{itemize}



\begin{verbatim}


-record(arg, {
clisock, % the socket leading to the peer client
client_ip_port, % {ClientIp, ClientPort} tuple
headers, % headers
req, % request
clidata, % The client data (as a binary in POST requests)
server_path, % The normalized server path
% (pre-querystring part of URI)
querydata, % For URIs of the form ...?querydata
% equiv of cgi QUERY_STRING
appmoddata, % (deprecated - use pathinfo instead) the remainder
% of the path leading up to the query
docroot, % Physical base location of data for this request
docroot_mount, % virtual directory e.g /myapp/ that the docroot
% refers to.
fullpath, % full deep path to yaws file
cont, % Continuation for chunked multipart uploads
state, % State for use by users of the out/1 callback
pid, % pid of the yaws worker process
opaque, % useful to pass static data
appmod_prepath, % (deprecated - use prepath instead) path in front
% of: <appmod><appmoddata>
prepath, % Path prior to 'dynamic' segment of URI.
% ie http://some.host/<prepath>/<script-point>/d/e
% where <script-point> is an appmod mount point,
% or .yaws,.php,.cgi,.fcgi etc script file.
pathinfo % Set to '/d/e' when calling c.yaws for the request
% http://some.host/a/b/c.yaws/d/e
% equiv of cgi PATH_INFO
}).

-record(http_request, {method,
path,
version}).


-record(headers, {
connection,
accept,
host,
if_modified_since,
if_match,
if_none_match,
if_range,
if_unmodified_since,
range,
referer,
user_agent,
accept_ranges,
cookie = [],
keep_alive,
location,
content_length,
content_type,
content_encoding,
authorization,
transfer_encoding,
x_forwarded_for,
other = [] % misc other headers
}).

\end{verbatim}


There are a number of \textit{advanced} fields in the \verb+#arg+
record such as \verb+appmod+ and \verb+opaque+ that will be discussed
in later chapters.

Now, we show some code which displays the content of the \verb+Arg+
\verb+#arg+ record. The code is available in \verb+yaws/www/arg.yaws+
and after a \verb+local_install+ a request to
\url{http://localhost:8000/arg.yaws} will run the code.

\begin{verbatim}

<html>

<h2> The Arg </h2>

<p>This page displays the Arg #argument structure
supplied to the out/1 function.

<erl>


out(A) ->
Req = A#arg.req,
H = yaws_api:reformat_header(A#arg.headers),
{ehtml,
[{h4,[], "The headers passed to us were:"},
{hr},
{ol, [],lists:map(fun(S) -> {li,[], {p,[],S}} end,H)},

{h4, [], "The request"},
{ul,[],
[{li,[], f("method: ~s", [Req#http_request.method])},
{li,[], f("path: ~p", [Req#http_request.path])},
{li,[], f("version: ~p", [Req#http_request.version])}]},

{hr},
{h4, [], "Other items"},
{ul,[],
[{li,[], f("clisock from: ~p", [inet:peername(A#arg.clisock)])},
{li,[], f("docroot: ~s", [A#arg.docroot])},
{li,[], f("fullpath: ~s", [A#arg.fullpath])}]},
{hr},
{h4, [], "Parsed query data"},
{pre,[], f("~p", [yaws_api:parse_query(A)])},
{hr},
{h4,[], "Parsed POST data "},
{pre,[], f("~p", [yaws_api:parse_post(A)])}]}.

</erl>

</html>

\end{verbatim}

The code utilizes four functions from the \verb+yaws_api+ module. The
\verb+yaws_api+ module is a general purpose www API module that
contains various functions that are handy while developing
\Yaws\ code. We will see many more of those functions during the
examples in the following chapters.

The functions used are:

\begin{itemize}
\item \verb+yaws_api:f/2+ --- alias for \verb+io_lib:format/2+. The
\verb+f/2+ function is automatically \verb+-included+ in all
\Yaws\ code.
\item \verb+yaws_api:reformat_header/1+ --- This function takes the
\#headers record and unparses it, that is reproduces regular text.
\item \verb+yaws_api:parse_query/1+ --- The topic of the next section.
\item \verb+yaws_api:parse_post/1+ --- Ditto.
\end{itemize}


\section{POSTs}

\subsection{Queries}

The user can supply data to the server in many ways. The most
common is to give the data in the actual URL.
If we invoke:

\verb+GET http://localhost:8000/arg.yaws?kalle=duck&goofy=unknown+

we pass two parameters to the \verb+arg.yaws+ page. That data is
URL-encoded by the browser and the server can retrieve the data by
looking at the remainder of the URL following the '?' character. If
we invoke the \verb+arg.yaws+ page with the above mentioned URL we get
as the result of \verb+yaws_parse_query/1+:

$kalle = duck$

$goofy = unknown$

In \Erlang\ terminology, the call \verb+yaws_api:parse_query(Arg)+ returns
the list:
\begin{verbatim}
[{"kalle", "duck"}, {"goofy", "unknown"}]
\end{verbatim}

Both the key and the value are strings.
Hence, a web page can contain URLs with a
query and thus pass data to the web server. This scheme works both
with \verb+GET+ and \verb+POST+ requests. It is the easiest way to
pass data to the Web server since no form is required in the web page.


\subsection{Forms}

In order to \verb+POST+ data a form is required. Say that we have a
page called \verb+form.yaws+ that contain the following code:

\begin{verbatim}
<html>
<form action="/post_form.yaws"
method="post"

<p> A Input field
<input name="xyz" type="text">
<input type="submit">
</form>
</html>
\end{verbatim}

This will produce a page with a simple input field and a submit button.

\begin{figure}[h]
\begin{center}

\includegraphics[scale=0.6] {a}

\end{center}
\end{figure}


If we enter something---say, ``Hello there''---in the input field and
click the submit button the client will request the page indicated in
the ``action'' attribute, namely \verb+post_form.yaws+.

If that \Yaws\ page has the following code:

\begin{verbatim}
out(A) ->
L = yaws_api:parse_post(A),
{html, f("~p", [L])}
\end{verbatim}

The user will see the output

\begin{verbatim}
[{"xyz", "Hello there"}]
\end{verbatim}

The differences between using the query part of the URL
and a form are the following:

\begin{itemize}
\item Using the query arg only works in a \verb+GET+ request. We parse
the query argument with the function
\verb+yaws_api:parse_query(Arg)+

\item If we use a form and \verb+POST+ the user data the client will
transmit the user data in the body of the request. That is, the
client sends a request to get the page using the \verb+POST+ method
and it then attaches the user data---encoded---into the body of the
request.

A \verb+POST+ request can have a query part in its URL as well as user
data in the body.
\end{itemize}


\section{POSTing files}

It is possible to upload files from the client to the server by means
of \verb+POST+. We indicate this in the form by telling the browser
that we want a different encoding. Here is an example form that does
this:
\begin{verbatim}

out(A) ->
Form =
{form, [{enctype, "multipart/form-data"},
{method, post},
{action, "file_upload_form.yaws"}],
[{input, [{type, submit}, {value, "Upload"}]},
{input, [{type,file}, {width, "50"}, {name, foo}]}]},
{ehtml, {html,[], [{h2,[], "A simple file upload page"},
Form]}}.

\end{verbatim}

As shown in the figure, the page delivers the entire HTML page with
enclosing \verb+html+ markers.


\begin{figure}[h]
\begin{center}

\includegraphics[scale=0.6] {b}

\end{center}
\end{figure}

The user gets an option to browse the local host for a file
or the user can explicitly fill in the file name in the input
field. The file browsing part is automatically taken care of by the
browser.

The action field in the form states that the client shall POST to a
page called \verb+file_upload_form.yaws+. This page will get the
contents of the file in the body of the \verb+POST+ message. To read
it, we use the \verb+yaws_multipart+ module, which provides the
following capabilities:

\begin{enumerate}
\item It reads all parameters --- files uploaded and other simple
parameters.
\item It takes a few options to help file uploads. Specifically:
\begin{enumerate}
\item \verb+{max_file_size, MaxBytes}+: if the file size in bytes
exceeds \verb+MaxBytes+, return an error
\item \verb+no_temp_file+: read the uploaded file into memory without
any temp files
\item \verb+{temp_file,FullFilePath}+: specify \verb+FullFilePath+ for
the temp file; if not given, a unique file name is generated
\item \verb+{temp_dir, TempDir}+: specify \verb+TempDir+ as the
directory to store the uploaded temp file; if this option is not
provided, then by default an OS-specific temp directory such as
\verb+/tmp+ is used
\item \verb+list+: return file data in list form; this is the default
\item \verb+binary+: return file data in binary form
\end{enumerate}
\end{enumerate}

Note that the \verb+list+ and \verb+binary+ options affect only file
data, not filenames, headers, or other parameters associated with each
file. These are always returned as strings.

Just call \verb+yaws_multipart:read_multipart_form+ from your
\verb+out/1+ function and it'll return a tuple with the first element
set to one of these three atoms:

\begin{itemize}
\item \verb+get_more+: more data needs to be read; return this tuple
directly to \Yaws\ from your \verb+out/1+ function and it will call
your \verb+out/1+ function again when it has read more \verb+POST+
data, at which point you must call \verb+read_multipart_form+ again
\item \verb+done+: multipart form reading is complete; a
\verb+dict+ full of parameters is returned
\item \verb+error+: an error occurred
\end{itemize}

The \verb+dict+ returned with \verb+done+ allows you to query it for
parameters by name. For file upload parameters, it returns one of the
following lists:

\begin{verbatim}
[{filename, "name of the uploaded file as entered on the form"},
{value, Contents_of_the_file_all_in_memory} | _T]
\end{verbatim}

or:

\begin{verbatim}
[{filename, "name of the uploaded file as entered on the form"},
{temp_file, "full pathname of the temp file"} | _T]
\end{verbatim}

Some multipart/form messages also headers such as \verb+Content-Type+
and \verb+Content-Transfer-Encoding+ for different subparts of the
message. If these headers are present in any subpart of a
multipart/form message, they're also included in that subpart's
parameter list, like this:

\begin{verbatim}
[{filename, "name of the uploaded file as entered on the form"},
{value, Contents_of_the_file_all_in_memory},
{content_type, "image/png"} | _T]
\end{verbatim}

Note that for the temporary file case, it's your responsibility to
delete the file when you're done with it.

Here's an example:

\begin{verbatim}
-module(my_yaws_controller).
-export([out/1]).

out(Arg) ->
Options = [no_temp_file],
case yaws_multipart:read_multipart_form(Arg, Options) of
{done, Params} ->
io:format("Params : ~p~n", [Params]),
{ok, [{filename, FileName},{value,FileContent}|_]} =
dict:find("my_file", Params),
AnotherParam = dict:find("another_param", Params);
%% do something with FileName, FileContent and AnotherParam
{error, Reason} ->
io:format("Error reading multipart form: ~s~n", [Reason]);
Other -> Other
end.
\end{verbatim}

Here, \verb+my_yaws_controller+ is a user-defined module compiled as
usual with \verb+erlc+ with the resulting \verb+.beam+ file placed in
the \Yaws\ load path. The module is then registered with \Yaws\ as an
\emph{appmod} to allow it to receive and process requests---see
section \ref{appmods} for more details.

\chapter{Mode of operation}

\section{On-the-fly compilation}
When the client requests a \Yaws\ page, \Yaws\ will look in its caches
(there is one cache per virtual server) to see if it finds the
requested page in the cache. If \Yaws\ doesn't find the page in the
cache, it will compile the page. This only happens the first time a
page is requested. Say that the page is 400 bytes big and has the
following layout:


\begin{figure}[h]
\begin{center}

\includegraphics[scale=0.4] {layout}

\end{center}
\end{figure}

The \Yaws\ server will then parse the file and produce a structure
which makes it possible to readily deliver the page without parsing
the next time the same page is requested.

When shipping the page it will
\begin{enumerate}
\item Ship the first 100 bytes from the file
\item Evaluate the first \Erlang\ chunk in the file and ship the output
from the \verb+out/1+ function in that chunk. It will also jump ahead
in the file and skip 120 bytes.
\item Ship 80 bytes of HTML code
\item Again evaluate an \Erlang\ chunk, this time the second and jump
ahead 60 bytes in the file.
\item And finally ship 140 bytes of HTML code to the client
\end{enumerate}

\Yaws\ writes the source output of the compilation into a directory
\verb+/tmp/yaws/$UID+. The beam files are never written to a file.
Sometimes it can be useful to look at the generated source code files,
for example if the \Yaws{}\slash \Erlang\ code contains a compilation
error which is hard to understand.


\section{Evaluating the Yaws Code}

All client requests will execute in their own \Erlang\ process.
For each group of virtual hosts on the same IP:PORT pair
one \Erlang\ process listens for incoming requests.

This process spawns acceptor processes for each incoming request.
Each acceptor process reads and parses all the HTTP headers from the
client. It then looks at the \verb+Host:+ header to figure out which
virtual server to use, i.e. which docroot to use for this particular
request. If the \verb+Host:+ header doesn't match any server from
\textit{yaws.conf} with that IP:PORT pair, the first one from
\textit{yaws.conf} is chosen.

By default \Yaws\ will not ship any data at all to the client
while evaluating a \Yaws\ page. The headers as well as the generated
content are accumulated and not shipped to the client until the
entire page has been processed.


\chapter{SSL}

Secure Socket Layer (SSL) is a protocol used on the Web for delivering
encrypted pages to the WWW client. SSL is widely deployed on the
Internet and virtually all bank transactions as well as all online
shopping today is done with SSL encryption. There are many good
sources on the net that describe SSL in detail, so we will not try to
do that here. See for example
\url{http://www.tldp.org/HOWTO/SSL-Certificates-HOWTO/}, which
describes how to manage certificates and keys.

In order to run an SSL server we must have a certificate. Either we
can create a so-called self-signed certificate ourselves or buy a
certificate from one of the many CA's (Certificate Authorities) on the
net. \Yaws\ uses the OTP interface to OpenSSL.

To setup a \Yaws\ server with SSL we could have a \textit{yaws.conf}
file that looks like:

\begin{verbatim}

 logdir = /var/log/yaws

<server www.funky.org>
               port = 443
               listen = 192.168.128.32
               docroot = /var/yaws/www.funky.org
               <ssl>
                  keyfile = /etc/funky.key
                  certfile = /etc/funky.cert
                  password = gazonk
               </ssl>
       </server>
\end{verbatim}

This is the easiest possible SSL configuration. The configuration
refers to a certificate file and a key file. The certificate file
must contain the name "www.funky.org" as it "Common Name".

The keyfile is the private key file and it is encrypted using
the password "gazonk".


\chapter{Applications}

\Yaws\ is well suited for Web applications. In this chapter we will
describe a number of application templates. Code and strategies that
can be used to build Web applications.

There are several ways of starting applications from \Yaws{}.

\begin{itemize}
\item The first and most easy variant is to specify the
  \verb+-r Module+ flag to the \Yaws\ startup script. This will
  \verb+apply(Module,start,[])+

\item We can also specify \verb+runmods+ in the \textit{yaws.conf}
  file. It is possible to have several modules specified if want the
  same \Yaws\ server to run several different applications.

\begin{verbatim}

runmod = myapp
runmod = app_number2

\end{verbatim}

\item It is also possible to do it the other way around, let the main
  application start \Yaws{}. We call this embedded mode, which we will
  discuss in chapter \ref{embedded}.

\end{itemize}



\section{Login scenarios}

Many Web applications require the user to login. Once the user has
logged in the server sets a cookie and then the user will be
identified by help of the cookie in subsequent requests.

\subsection{The session server}
The cookie is passed in the headers and is available to the
\Yaws\ programmer in the \verb+Arg+ \verb+#arg+ record. The
\Yaws\ session server can help us to maintain a state for a user while
the user is logged in to the application. The session server has the
following 5 API functions to aid us:

\begin{enumerate}
\item \verb+yaws_api:new_cookie_session(Opaque)+ --- This function
  initiates a new cookie-based session. The \verb+Opaque+ data is
  typically some application-specific structure which makes it
  possible for the application to read a user state, or it can be the
  actual user state itself.

\item \verb+yaws_api:cookieval_to_opaque(Cookie)+ --- This function
  maps a cookie to a session.

\item \verb+yaws_api:replace_cookie_session(Cookie, NewOpaque)+ ---
  Replace the opaque user state in the session server with
  \verb+NewOpaque+.

\item \verb+yaws_api:delete_cookie_session(Cookie)+ --- This function
  should typically be called when the user logs out or when our web
  application decides to automatically logout the user.

\end{enumerate}

All cookie-based applications are different but they have some things
in common. In the following examples we assume the existence of a
function \verb+myapp:auth(UserName, Passwd)+ and it returns \verb+ok+
or \verb+{error, Reason}+.

Let's assume the following record:

\begin{verbatim}

-record(session, {user,
                  passwd,
                  udata = []}).

\end{verbatim}

The following function is a good template function to check the
cookie.

\begin{verbatim}

get_cookie_val(CookieName, Arg) ->
    H = Arg#arg.headers,
    yaws_api:find_cookie_val(CookieName, H#headers.cookie).



check_cookie(A, CookieName) ->
    case get_cookie_val(CookieName, A) of
        [] ->
            {error, "not logged in"};
        Cookie ->
            yaws_api:cookieval_to_opaque(Cookie)
    end.

\end{verbatim}

We need to check all requests and make sure the session\_server has
our cookie registered as an active session. Also, if a request comes
in without a working cookie we want to present a login page instead of
the page the user requested. Another quirky issue is that the pages
necessary for display of the login page must be shipped without
checking the cookie. The next sections explain how these needs can be
met.

\subsection{Arg rewrite}

In this section we describe a feature whereby the user is allowed to
rewrite the \verb+Arg+ at an early stage in the \Yaws\ server. We do
that by specifying an \verb+arg_rewrite_mod+ in the \textit{yaws.conf}
file.

\begin{verbatim}
arg_rewrite_mod = myapp
\end{verbatim}


Then in the \verb+myapp+ module we have:

\begin{verbatim}
arg_rewrite(Arg) ->
    OurCookieName = "myapp_sid"
    case check_cookie(A, OurCookieName) of
        {error, _} ->
            do_rewrite(Arg);
        {ok, _Session} ->
            %return Arg untouched
            Arg
    end.

%% these pages must be shippable without a good cookie
login_pages() ->
    ["/banner.gif", "/login.yaws", "/post_login.yaws"].

do_rewrite(Arg) ->
    Req = Arg#arg.req,
    {abs_path, Path} = Req#http_request.path,
    case lists:member(Path, login_pages()) of
        true ->
            Arg;
        false ->
            Arg#arg{req = Req#http_request{path = {abs_path, "/login.yaws"}},
                    state = {abs_path, Path}}
    end.

\end{verbatim}

Our arg rewrite function lets all \verb+Arg+s go through untouched
that either have a good cookie or belong to a set of predefined pages
that are acceptable to get without being logged in. If we decide that
the user must log in, we change the path of the request, thereby
making the \Yaws\ server ship a login page instead of the page the
user requested. We also set the original path in the \verb+Arg+ state
argument so that the login page can redirect the user to the original
page once the login procedure is finished.

Within an arg rewrite function, examining and modifying HTTP headers can be
achieved using the following functions from the \verb+yaws_api+ module:

\begin{itemize}
\item \verb+set_header/2+, \verb+set_header/3+
\item \verb+get_header/2+, \verb+get_header/3+
\item \verb+delete_header/2+
\end{itemize}

All functions operate on instances of the \verb+#headers{}+ record type
defined in the \verb+yaws_api.hrl+ include file.

\subsection{Authenticating}

Now we're approaching the \verb+login.yaws+ page, the page that
displays the login prompt to the user. The login page consists of two
parts: one part that displays the login data as a form, and one form
processing page that reads the data the user entered in the login
fields and performs the actual authentication.

The login page performs a tiny well-known Web trick where it passes
the original URL request in a hidden field in the login page and
thereby passing that information to the form processing page.

The page \verb+login.yaws+:

\begin{verbatim}
<erl>

out(A) ->
    {ehtml,
     {html,[],
      [{h2, [], "Login page"},
       {hr},
       {form, [{action,"/login_post.yaws"},
               {method,post}],

        [{p,[], "Username"}, {input, [{type,text},{name,uname}]},
         {p,[],"Password"}, {input, [{type,password},{name,passwd}]},
         {input, [{type,submit},{value,"Login"}]},
         {input, [{type,hidden},{name,url},
                  {value, A#arg.state}]}]}]}}.

</erl>
\end{verbatim}



The form processing page which gets the \verb+POST+ data from the code
above:

\begin{verbatim}


<erl>

-include("myapp.hrl").
%% we have the session record there
%% we must set the include_path in the yaws.conf file
%% in order for the compiler to find that file

kv(K,L) ->
    {value, {K, V}} = lists:keysearch(K,1,L),
    V.

out(A) ->
    L = yaws_api:parse_post(A),
    User = kv(user, L),
    Pwd = kv(passwd, L),
    case myapp:auth(User, Pwd) of
        ok ->
            S = #session{user = User,
                         passwd = Pwd,
                         udata = []},
            %% Now register the session to the session server
            Cookie = yaws_api:new_cookie_session(S),
            [{redirect_local, kv(url, L)},
              yaws_api:setcookie("myapp_sid",Cookie)]
        Err ->
            {ehtml,
             {html, [],
              {p, [], f("Bad login: ~p",[Err])}}}
    end.

</erl>



\end{verbatim}

The function returns a list of two new (not previously discussed)
return values: instead of returning HTML output as in
\verb+{html, Str}+ or \verb+{ehtml,Term}+ we return a list of two new
values. (There are many different possible return values from the
\verb+out/1+ function and they will all be described later.) The two
new values are:

\begin{enumerate}

\item The tuple \verb+{redirect_local, Path}+ makes the \Yaws\ web
  server return a 302 redirect to the specified \verb+Path+.
  Optionally a different status code can be supplied which will be
  used in place of 302, e.g. \verb+{redirect_local, Path, 307}+.

\item \verb+yaws_api:setcookie("myapp_sid",Cookie)+ generates a
  \verb+Set-Cookie+ header.
\end{enumerate}

Now if we put all this together we have a full-blown cookie-based
login system. The last thing we did in the form processing code was
to register the session with the session server thereby letting any
future requests go straight through the \verb+Arg+ rewriter.

This way both \Yaws\ pages as well as all or some static content
is protected by the cookie login code.

\subsection{Database driven applications}

We can use code similar to the code in the previous section to associate
a user session to entries in a database. Mnesia fits perfectly
together with \Yaws\ and keeping user persistent state in Mnesia is
both easy and convenient.

Once the user has logged in we can typically use the user name as key
into the database. We can mix \verb+ram_tables+ and \verb+disc_tables+
to our liking. The Mnesia database must be initialized via
\verb+create_table/2+ before it can be used. This is typically done
while installing the web application on a machine.

Another option is to let the application check that Mnesia
is initialized whenever the application starts.

If we don't want or need to use Mnesia, it's of course possible
to use a simple \verb+dets+ file or a text file as well.

\section{Appmods}
\label{appmods}

Appmods is mechanism to invoke different applications based upon the
URL. A URL---as presented to the web server in a request---has a path
part and a query part.

It is possible to install several appmods in the \textit{yaws.conf}
file as shown below:

\begin{verbatim}

appmods = foo myapp

\end{verbatim}

Now, if the user requests a URL where any component in the
directory path is an appmod, the parsing of the URL will terminate
there and instead of reading the actual file from the disk, \Yaws\ will
invoke the appmod with the remainder of the path inserted into
\verb+Arg#arg.appmoddata+.

Say the user requests the URL
\url{http://www.funky.org/myapp/xx/bar.html}. \Yaws\ will not ship
the file \verb+bar.html+ to the client, instead it will invoke
\verb+myapp:out(Arg)+ with \verb+Arg#arg.appmoddata+ set to the string
\verb+xx/bar.html+. Any optional query data---that is, data that
follows the first '?' character in the URL---is removed from the path
and passed as \verb+Arg#arg.querydata+.

Appmods can be used to run applications on a server. All requests
to the server that has an appmod in the URL will be handled by that
application. If the application decides that it want to
ship a page from the disk to the client, it can return the
tuple \verb+{page, Path}+. This return value will make \Yaws\ read
the page from the disk, possibly add the page to its cache of
commonly accessed pages and ship it back to the client.

The \verb+{page, Path}+ return value is equivalent to a
redirect, but it removes an extra round trip, and is thus faster.

Appmods can also be used to fake entire directory hierarchies
that don't exist on disk.


\section{The opaque data}

Sometimes an application needs application-specific data such as the
location of its data files. There exists a mechanism to pass
application-specific configuration data from the \Yaws\ server to the
application.

When configuring a server we have an opaque field in the configuration
file that can be used for this purpose. Say we have the following
fields in the config file:

\begin{verbatim}

<server foo>
    listen = 192.168.128.44
    <opaque>
        foo = bar
        somefile = /var/myapp/db
        myname = hyber
    </opaque>
</server>
\end{verbatim}

This will create a normal server that listens to the specified IP address.
An application has access to the opaque data that was specified
in that particular server through \verb+Arg#arg.opaque+.

If we have the opaque data specified above, the \verb+Arg+ opaque
field will have the value:

\begin{verbatim}

[{foo, "bar"},
 {somefile, "/var/myapp/db"},
 {myname, "hyber"}
]

\end{verbatim}


\section{Customizations}

When actually deploying an application at a live site, some of the
standard \Yaws\ behaviors are not acceptable. Many sites want to
customize the web server behavior when a client requests a page that
doesn't exist on the web server. The standard \Yaws\ behavior is to
reply with status code 404 and a message explaining that the page
doesn't exist.

Similarly, when \Yaws\ code crashes, the reason for the crash is
displayed in the Web browser. This is very convenient while
developing a site but not acceptable in production.


\subsection{404 File not found}

We can install a special handler for 404 messages. We do that by
specifying a \verb+errormod_404+ in the \textit{yaws.conf} file.

If we have:

\begin{verbatim}
<server foo>
  ..
  ..
  ..
  errormod_404 = myapp

</server>

\end{verbatim}

When \Yaws\ gets a request for a file that doesn't exist, it invokes
the \verb+errormod_404+ module to generate both the status code as
well as the content of the message.

If \verb+Module+ is specified as the \verb+errormod_404+ module,
\Yaws\ will invoke \verb+Module:out404(Arg, GC, SC)+, passing the
arguments as described below:

\begin{itemize}
\item \verb+Arg+ is an \verb+#arg{}+ record

\item \verb+GC+ is a \verb+#gconf{}+ record (defined in \verb+yaws.hrl+)

\item \verb+SC+ is a \verb+#sconf{}+ record (defined in
  \verb+yaws.hrl+)
\end{itemize}

The function can and must do the same things that a normal
\verb+out/1+ function does.


\subsection{Crash messages}

We use a similar technique for generating the crash messages: we
install a module in the \textit{yaws.conf} file and let that module
generate the crash message. We have:

\begin{verbatim}
errormod_crash = Module
\end{verbatim}

The default is to display the entire formatted crash message in the
browser. This is good for debugging but not good for production.

If \verb+Module+ is specified as the \verb+errormod_crash+ module, the
function \verb+Module:crashmsg(Arg, SC, Str)+ will be called. The
\verb+Str+ argument is the real crash message formatted as a string.

\section{Stream content}

If the \verb+out/1+ function returns the tuple
\verb+{content, MimeType, Content}+ \Yaws\ will ship that data to the
Client. This way we can deliver dynamically generated content to the
client which is of a different MIME type than "text/html".

If the generated response is very large and it not possible or
practical to generate the whole thing, we can return the value:

\begin{verbatim}
{streamcontent, MimeType, FirstChunk}
\end{verbatim}

\noindent which delivers data back to the client using HTTP chunked
transfer (see RFC 2616 section 3.6.1) and then from a different
\Erlang\ process deliver the remaining chunks by using the functions
described below:

\begin{enumerate}
\item \verb+yaws_api:stream_chunk_deliver(YawsPid, Data)+ where the
  \verb+YawsPid+ is the process id of the \Yaws\ worker process. That
  pid is available in \verb+Arg#arg.pid+.

\item \verb+stream_chunk_end(YawsPid)+ which must be called to
  indicate the end of the stream.
\end{enumerate}

A streaming alternative is also available for applications that need a
more direct way to deliver data to clients, such as those dealing with
data too large to buffer in memory but not wishing to use chunked
transfer, or applications that use long-polling (Comet) techniques
that require them to hold client connections open for extended
periods. For these situations we can return the value:

\begin{verbatim}
{streamcontent_from_pid, MimeType, Pid}
\end{verbatim}

\noindent to tell \Yaws\ we wish to deliver data of mime type
\verb+MimeType+ to the client from process \verb+Pid+. In this case,
\Yaws\ will prepare the socket for delivery from \verb+Pid+ and then
send one of the following messages to \verb+Pid+:
\begin{itemize}
\item \verb+{ok, YawsPid}+ tells \verb+Pid+ that it is now OK to
  proceed with sending data back to the client using the socket. The
  socket is accessible as \verb+Arg#arg.clisock+.

\item \verb+{discard, YawsPid}+ informs \verb+Pid+ that it should not
  attempt to use the socket, typically because the requested HTTP
  method requires no response body.
\end{itemize}

We call one of the following functions to send data:
\begin{itemize}
\item \verb+yaws_api:stream_process_deliver(Socket, IoList)+ sends data
  \verb+IoList+ using socket \verb+Socket+ without chunking the data. To
  ensure chunking is not in effect, return

\begin{verbatim}
{header, {transfer_encoding, erase}}
\end{verbatim}

  in a list with the \verb+streamcontent_from_pid+ directive (which must
  always be last in such a list).

\item \verb+yaws_api:stream_process_deliver_chunk(Socket, IoList)+
  sends data \verb+IoList+ using socket \verb+Socket+ but converts
  the data into chunked transfer form before sending it.
\end{itemize}

Pids using chunked transfer must indicate the end of their transfer by
calling the following function:
\begin{itemize}
\item \verb+yaws_api:stream_process_deliver_final_chunk(Socket, IoList)+
\end{itemize}

which delivers a special HTTP chunk to mark the end of the data
transfer to the client.

Finally, \verb+Pid+ must always call
\verb+yaws_api:stream_process_end(Socket, YawsPid)+ when it finishes
sending data or when it receives the \verb+{discard, YawsPid}+ message
from \Yaws\ --- this is required to inform \Yaws\ that \verb+Pid+ has
finished with the socket and will not use it directly anymore. If the
application has to close the socket while it's in control of it,
though, it must pass the atom \verb+closed+ as the first argument to
\verb+yaws_api:stream_process_end+ in place of the socket to inform
\Yaws\ that the socket has been closed and it should no longer attempt
to use it.

App\-li\-ca\-tions that use the \verb+streamcontent_from_pid+
directive that also want to a\-void chunked transfer encoding for
their streams should be sure to include a set\-ting for the
\verb+Content-Length+ header in their \verb+out/1+ return
value. \Yaws\ au\-to\-mat\-i\-cal\-ly sets the
\verb+Transfer-Encoding+ head\-er to \verb+chunked+ if it does not
detect a \verb+Content-Length+ header.

\section{All out/1 return values}

\begin{itemize}


\item \verb+{html, DeepList}+ This assumes that \verb+DeepList+ is
  formatted HTML code. The code will be inserted in the page.

\item \verb+{ehtml, Term}+ This will transform the \Erlang\ term
  \verb+Term+ into a stream of HTML content.

\item \verb+{content, MimeType, Content}+ This function will make the
  web server generate different content than HTML. This return value
  is only allowed in a \Yaws\ file which has only one
  \verb+<erl> </erl>+ part and no html parts at all.

\item \verb+{streamcontent, MimeType, FirstChunk}+ This return value
  plays the same role as the \verb+content+ return value above.
  However it makes it possible to stream data to the client using HTTP
  chunked transfer if the \Yaws\ code doesn't have access to all the
  data in one go. (Typically if a file is very large or if data
  arrives from back end servers on the network.)

\item
  \verb+{streamcontent_with_timeout, MimeType, FirstChunk, Timeout}+
  Similar to the above, but with an explicit timeout. The default
  timeout is 30 secs, i.e. if the application fails to deliver data to
  the \Yaws\ process, the streaming will stop. This is often not the
  desired behaviour in Comet/Ajax applications. It's possible to
  provide 'infinity' as the timeout.

\item \verb+{streamcontent_from_pid, MimeType, Pid}+ This return value
  is similar to the \verb+streamcontent+ return value above. However
  it makes it possible to stream data to the client directly from an
  application process to the socket. This approach can be useful for
  applications that employ long-polling (Comet) techniques, for
  example, and for applications wanting to avoid buffering data or
  avoid HTTP chunked mode transfer for streamed data.

\item \verb+{streamcontent_with_size, Sz, MimeType, Pid}+ This is
  similar to the \verb+streamcontent+ return value above. However it
  makes it possible to stream data to the client by setting the
  content length of the response. As the opposite of other ways to
  stream data, in this case, the response is not chunked encoded.


\item \verb+{header, H}+ Accumulates a HTTP header. Used by for
  example the \verb+yaws_api:setcookie/2-6+ function.

\item \verb+{header, {H, erase}}+ A specific case of the previous
  directive; use this to remove a specific header from a response. For
  example, streaming applications and applications using server-sent events
  (see \url{http://www.w3.org/TR/eventsource/ }) should use
  \verb+{header, {transfer_encoding, erase}}+ to turn off chunked encoding
  for their responses.

\item \verb+{allheaders, HeaderList}+ Will clear all previously
  accumulated headers and replace them.

\item \verb+{status, Code}+ Sets the response HTTP status code to
  \verb+Code+.

\item \verb+break+ Will stop processing of any consecutive chunks of
  erl or HTML code in the \Yaws\ file.

\item \verb+ok+ Do nothing.

\item \verb+flush+ Flush remaining data sent by the client.

\item \verb+{redirect, Url}+ Erase all previous headers and accumulate
  a single HTTP \verb+Location+ header. Set the status code to 302.

\item \verb+{redirect, Url, Status}+ Same as redirect above with the
  additional option of supplying the status code. The default for a
  redirect is 302 but 301, 303 and 307 are also valid redirect status
  codes.

\item \verb+{redirect_local, Path}+ Does a redirect to the same
  \url{Scheme://Host:Port/Path} in which we are currently
  executing. \verb+Path+ can be either be the path directly
  (equivalent to \verb+abs_path+), or one of \verb+{{abs_path, Path}+
  or \verb+{{rel_path, RelativePath}}+

\item \verb+{redirect_local, Path, Status}+ Same as
  \verb+redirect_local+ above with the additional option of supplying
  the status code. The default for a redirect is 302 but 301, 303 and
  307 are also valid redirect status codes.

\item \verb+{get_more, Cont, State}+ When we are receiving large
  \verb+POST+s we can return this value and be invoked again when more
  data arrives.

\item \verb+{page, Page}+ Make \Yaws\ return a different local page
  than the one being requested.

\item \verb+{page, {Options, Page}}+ Like the above, but supplying an
  additional deep list of options. For now, the only type of option
  is \verb+{header, H}+ with the effect of accumulating the HTTP
  header \verb+H+ for page \verb+Page+.

\item \verb+{websocket, CallbackModule, Options}+ Tell \Yaws\ to use
  \verb+CallbackModule+ as a WebSockets Protocol handler for traffic
  on the client socket. See chapter \ref{websockets} for more details.

\item \verb+[ListOfValues]+ It is possible to return a list of the above defined
  return values. Any occurrence of the atoms \verb+streamcontent+,
  \verb+streamcontent_with_timeout+,
  \verb+streamcontent_with_size+,\\
  \verb+streamcontent_from_pid+, \verb+get_more+, \verb+page+ or \verb+break+ in
  this list is legal only if it is the last position of the list. If not,
  remaining values in the list are ignored.

\end{itemize}



\chapter{Debugging and Development}

\Yaws\ has excellent debugging capabilities. First and foremost we
have the ability to run the web server in interactive mode by means of
the command line switch \verb+-i+, which gives us a regular
\Erlang\ command line prompt we can use to compile helper code or
reload helper code. Furthermore all error messages are displayed
there. If a \verb+.yaws+ page producees any regular \Erlang\ I\slash
O, that output will be displayed at the \Erlang\ prompt, assuming we
are running in interactive mode.

If we give the command line switch \verb+-d+ we get some additional
error messages. Also \Yaws\ does some additional checking of user
supplied data such as headers.

\section{Logs}
\Yaws\ produces various logs. All log files are written into the
\Yaws\ logdir directory. This directory is specified in the config
file.

We have the following log files:

\begin{itemize}
\item The access log. Access logging is turned on or off per server in
  the \textit{yaws.conf} file. If access\_log is turned on for a
  server, \Yaws\ will produce a log in Common Access Log Format called
  \textit{HostName:PortNumber.access}

\item The auth log. Auth logging is turned on or off per server in the
  \textit{yaws.conf} file. If auth\_log is turned on for a server,
  \Yaws\ will produce a log called \textit{HostName:PortNumber.auth}
  which contains all HTTP auth-related messages.

\item \textit{report.log} This file contains all error and crash
  messages for all virtual servers in the same file.

\item Trace files. The two command line flags \verb+-t+ and \verb+-T+ tells
\Yaws\ to trace all traffic or just all HTTP messages and write them to files.
\end{itemize}


\chapter{External scripts via CGI}

\Yaws\ can also interface to external programs generating dynamic
content via the Common Gateway Interface (CGI). This has to be
explicitly enabled for a virtual host by listing \verb+cgi+ in the
\verb+allowed_scripts+ line in the configuration file. Any request
for a page ending in \verb+.cgi+ (or \verb+.CGI+) will then result in
trying to execute the corresponding file.

If you have a PHP executable compiled for using CGI in the \verb+PATH+
of the \Yaws\ server, you can enable PHP support by adding \verb+php+ to
\verb+allowed_scripts+. Requests for pages ending in \verb+.php+ will
then result in \Yaws\ executing \verb+php+ (configurable via
\verb+php_handler+) and passing the name of the corresponding file to
it via the appropriate environment variable.

These ways of calling CGI scripts are also available to \verb+.yaws+
scripts and appmods via the functions \verb+yaws_api:call_cgi/2+ and
\verb+yaws_api:call_cgi/3+. This makes it possible to write wrappers
for CGI programs, irrespective of the value of \verb+allowed_scripts+.

The author of this \Yaws\ feature uses it for self-written CGI programs
as well as for using a standard CGI package. You should not be
surprised however, should some scripts not work as expected due to an
incomplete or incorrect implementation of certain CGI meta-variables.
The author of this feature is interested in hearing about your
experiences with it. He can be contacted at \verb+carsten@codimi.de+.

\chapter{FastCGI}

\Yaws\ supports the responder role and the authorizer role of the
FastCGI protocol. See \verb+www.fastcgi.com+ for details on the
FastCGI protocol.

The benefits of using FastCGI include:
\begin{enumerate}
\item Unlike CGI, it is not necessary to spawn a new process for
every request; the application server can handle multiple requests
in a single process.
\item The fact that the application server can run on a different
computer benefits scalability and security.
\item The application server can be written in any language for
which a FastCGI library is available. Existing applications
which have been written for other web servers can be used with
\Yaws{}.
\item FastCGI can also be used to implement external authentication
servers (in addition to generating dynamic content).
\end{enumerate}

Support for FastCGI was added to \Yaws\ by Bruno Rijsman
(\verb+brunorijsman@hotmail.com+).

\section{The FastCGI Responder Role}

The FastCGI responder role allows \Yaws\ to communicate with an
application server running on a different (or on the same) computer
to generate dynamic content.

The FastCGI protocol (which runs over TCP) is used to send the request
information from \Yaws\ to the application server and to send the
response information (e.g. the generated dynamic content) from
the application server back to \Yaws{}.

FastCGI responders can be invoked in two ways:

\begin{enumerate}

\item
By including \verb+fcgi+ in the \verb+allowed_scripts+ line
in the configuration file (note that the default value for
\verb+allowed_scripts+ includes \verb+fcgi+).

In this case a request for any resource with the \verb+.fcgi+
extension will result in a FastCGI call to the application server to
dynamically generate the content.

Note: the \Yaws\ server will only call the application server if a file
corresponding to the resource name (i.e. a file with the \verb+.fcgi+
extension) exists locally on the \Yaws\ server. The contents of that
file are not relevant.

\item
By creating an appmod which calls \verb+yaws_api:call_fcgi_responder+.
See the \verb+yaws_api(5)+ man page for details.

\end{enumerate}

\section{The FastCGI Authorizer Role}

The FastCGI authorizer role allows \Yaws\ to communicate with an
authentication server to authenticate requests.

The FastCGI protocol is used to send the request information from
\Yaws\ to the authentication server and the authentication response
back from the authentication server to \Yaws{}.

If access is allowed, \Yaws\ proceeds to process the request normally.

If access is denied, the authentication server provides the
response which is sent back to the client. This is typically
a ``not authorized'' response or a redirect to a login page.

FastCGI authorizers are invoked by creating an appmod which
calls \verb+yaws_api:call_fcgi_authorizer+.
See the \verb+yaws_api(5)+ man page for details.

\section{The FastCGI Filter Role}

FastCGI defines a third role, the filter role, which
\Yaws\ does not currently support.


\section{FastCGI Configuration}

The following commands in the \textit{yaws.conf} file control the
operation of FastCGI.

If you use FastCGI, you \emph{must} include the \verb+fcgi_app_server+
setting in the configuration file to specify the host name (or IP address)
and TCP port of the FastCGI application server.

You may include the \verb+fcgi_trace_protocol+ setting to enable or disable
tracing of FastCGI protocol messages. This is useful for debugging.

You may include the \verb+fcgi_log_app_error+ setting to enable or disable
logging application errors (any output to stderr and non-zero exit codes).

You may include the \verb+extra_cgi_vars+ command to pass additional
environment variables to the application.


\chapter{Security}

\Yaws\ is of course susceptible to intrusions. \Yaws\ has the
ability to run under a different user than root, even if we need
to listen to privileged port numbers. Running as root is generally a
bad idea.

Intrusions can happen basically at all places in \Yaws\ code where the
\Yaws\ code calls either the BIF \verb+open_port+ or when \Yaws\ code
calls \verb+os:cmd/1+. Both \verb+open_port+ and \verb+os:cmd/1+
invoke the \verb+/bin/sh+ interpreter to execute its commands. If the
commands are nastily crafted bad things can easily happen.

All data that is passed to these two function must be carefully
checked.

Since \Yaws\ is written in \Erlang\ a large class of cracks are
eliminated since it is not possible to perform any buffer overrun
cracks on a \Yaws\ server. This is very good.


Another possible point of entry to the system is by providing a URL
which takes the client out from the docroot. This should not be
possible -- and the impossibility relies on the correctness of the URL
parsing code in \Yaws{}.

\section{WWW-Authenticate}
\Yaws\ has support for WWW-Authentication. WWW-Authenticate is a
standard HTTP scheme for the basic protection of files with a username
and password. When a client browser wants a protected file, it must send a
\verb+Authenticate: username:password+ header in the request. Note that
this is plain text. If there is no such header or the username and
password is invalid the server will respond with status code 401 and
the realm. Browsers will then tell the user that a username and
password is needed for ``realm'', and will resend the request after
the user enters the information.

WWW-Authentication is configured in the \textit{yaws.conf} file, in as
many \textit{<auth>} directives as you desire:

\begin{verbatim}
<server foo>
  docroot = /var/yaws/www/

..
..

  <auth>
    realm = secretpage
    dir = /protected
    dir = /anotherdir
    user = klacke:gazonk
    user = jonny:xyz
    user = ronny:12r8uyp09jksfdge4
  </auth>
</server>
\end{verbatim}


\Yaws\ will require one of the given username:password pairs for all
files in the \textit{/protected} and \textit{/anotherdir} directories.
Note that these directories are specified as a server path, that is,
the filesystem path that is actually protected here is
\textit{/var/yaws/www/protected} .


\chapter {Embedded mode}
\label{embedded}

\Yaws\ is a normal OTP application. It is possible to integrate \Yaws\
into another larger application. The \Yaws\ source tree must be
integrated into the larger application's build environment. \Yaws\ is
then simply started by \verb+application:start()+ from the larger
application's boot script, or the \Yaws\ components needed for the
larger application can be started individually under the application's
supervisor(s).

By default \Yaws\ reads its configuration data from a config file, the
default is \textit{/usr/local/etc/yaws/yaws.conf} . If \Yaws\ is integrated
into a larger application, however, that application typically has its
configuration data kept at some other centralized place. Sometimes we
may not even have a file system to read the configuration from if we
run a small embedded system.

\Yaws\ reads its application environment. If the environment key
\verb+embedded+ is set to \verb+true+, \Yaws\ starts in embedded mode.
Once started it must be fed a configuration, and that can be done
after \Yaws\ has started by means of the function
\verb+yaws_api:setconf/2+.

It is possible to call \verb+setconf/2+ several times to force \Yaws\ to
reread the configuration.

\section{Creating Global and Server Configurations}

The \verb+yaws_api:setconf/2+ function mentioned in the previous
section takes two arguments:

\begin{itemize}

\item a \verb+#gconf+ record instance, specifying global
  \Yaws\ configuration

\item a list of lists of \verb+#sconf+ record instances, each
  specifying configuration for a particular server instance

\end{itemize}

These record types are specified in \verb+yaws.hrl+, which is not
normally intended for inclusion by applications. Instead,
\Yaws\ provides the \verb+yaws_api:embedded_start_conf/1,2,3,4+
functions that allow embedded mode applications to specify
configuration data using property lists (lists of
\verb+{key, value}+ pairs).

The \verb+yaws_api:embedded_start_conf+ functions all return a tuple
containing the following four items:

\begin{itemize}

\item the atom \verb+ok+.

\item a list of lists of \verb+#sconf+ record instances. This variable
  is intended to be passed directly to\\* \verb+yaws_api:setconf/2+ as
  its second argument.

\item a \verb+#gconf+ record instance. This variable is intended to
  be passed directly to \verb+yaws_api:setconf/2+ as its first
  argument.

\item a list of supervisor child specification for the
  \Yaws\ components the embedded mode application's configuration
  specified should be started. This allows embedded mode applications
  to start \Yaws\ under its own supervisors.

\end{itemize}

Note that \verb+yaws_api:embedded_start_conf+ does not actually start
any servers, but rather it only returns the configuration information
and child specifications needed for the embedded mode application to
start and configure \Yaws\ itself.

If you have difficulty figuring out how to set up your \verb+#gconf+
or \verb+#sconf+ records for embedded mode, you should first consider
getting something running in non-embedded mode using a
\verb+yaws.conf+ file. Once you're satisfied with the setup and
\Yaws\ is running, execute the following command:

\begin{verbatim}
yaws --running-config
\end{verbatim}

This command will show the \Yaws\ configuration from your
\verb+yaws.conf+ file in terms of \verb+#gconf+ and \verb+#sconf+
records, thus showing you how to set up those records for embedded
mode.

\section{Starting Yaws in Embedded Mode}

An embedded mode application can start \Yaws\ in one of two ways:

\begin{itemize}

\item It can call \verb+yaws_api:embedded_start_conf+ to obtain
  configuration and \Yaws\ startup information as described in the
  previous section, start \Yaws\ under its own supervisors, and then
  pass the global and server configuration settings to
  \verb+yaws_api:setconf/2+.

\item It can call \verb+yaws:start_embedded/1,2,3,4+, each of which
  takes exactly the same arguments as the corresponding
  \verb+yaws_api:embedded_start_conf/1,2,3,4+ function. Instead of just
  returning start and configuration information, however,
  \verb+yaws:start_embedded+ also starts and configures \Yaws{}, which
  can be more convenient but does not allow the embedded mode
  application any supervision control over \Yaws{}.

\end{itemize}

Both of these functions take care of setting the environment key
\verb+embedded+ to \verb+true+. Neither approach requires any special
settings in the embedded mode application's \textit{.app} file nor any
special command-line switches to the \Erlang\ runtime.

For an example of how to use \verb+yaws_api:embedded_start_conf+ along
with \verb+yaws_api:setconf+, please see the files
\verb+www/ybed_sup.erl+ and \verb+www/ybed.erl+ in the
\Yaws\ distribution.

\chapter{The config file - yaws.conf}

In this section we provide a complete listing of all possible
configuration file options. The configuration contains two distinct
parts: a global part which affects all the virtual hosts and a server
part where options for each virtual host is supplied.

\section{Global Part}

\begin{itemize}


\item \verb+logdir = Directory+ ---
              All \Yaws\ logs will be written to files in this
              directory. There are several different log files
              written by \Yaws{}.

              \begin{itemize}
              \item \verb+report.log+ --- this is a text file that contains all
              error logger printouts from \Yaws{}.
              \item \verb+<Host>.access+ --- for each virtual host
                served by \Yaws{}, a file \verb+<Host>.access+ will be
                written which contains an access log in Common Log
                Format.
              \item \verb+<Host>.auth+ --- for each virtual host served by
              \Yaws{}, a file \verb+<Host>.auth+ will be written which
              contains all HTTP auth related messages.
              \item \verb+trace_<YYYYMMDD_hhmmss>+ - Trace files are written in
              this subdirectory, suffixed by the creation date.
              \begin{itemize}
              \item \verb+trace.<Pid>.http+ - this file contains the HTTP
              trace if that is enabled, where \verb+Pid+ is the process id
              handling the TCP connection.
              \item \verb+trace.<Pid>.traffic+ - this file contains the
              traffic trace if that is enabled, where \verb+Pid+ is the
              process id handling the TCP connection.
              \end{itemize}
              \end{itemize}

              Note that \verb+<Host>.access+ and \verb+<Host>.auth+ files will
              be used only if the directive \verb+logger_mod+ is not set or set
              to \verb+yaws_log+.

              The default value for logdir is "."

\item \verb+ebin_dir = Directory+ ---
              This directive adds Directory to the \Erlang\ search
              path. It is possible to have several of these command
              in the configuration file.

\item \verb+id = String+ ---
              It is possible run multiple Yaws servers on the same machine. We
              use the id of a Yaws server to control it using the different
              control commands such as:
\begin{verbatim}
  # /usr/local/bin/yaws --id foobar --stop
\end{verbatim}
               To stop the Yaws server with id "foobar". Each \Yaws\ server will
               write its internals data into a file called \$HOME/.yaws/yaws/ID
               where ID is the identity of the server. Yaws also creates a file
               called \${VARDIR}/run/yaws/ctl-\${ID} which contain the port
               number where the server is listening for control commands. The
               default id is "default".

\item \verb+server_signature = String+ ---
              This directive sets the "Server: " output header to the custom
              value. The default value is "yaws/VSN, Yet Another Web Server".

\item \verb+include_dir = Directory+ ---
              This directive adds Directory to the path of directories
               where the \Erlang\ compiler searches for
              include files. We need to use this if we want to
              include \textit{.hrl} files in our \Yaws\ \Erlang\ code.

\item \verb+max_num_cached_files = Integer+ ---
              \Yaws\ will cache small files such as commonly
              accessed GIF images in RAM. This directive sets a
              maximum number on the number of cached files. The
              default value is 400.

\item \verb+max_num_cached_bytes = Integer+ ---
              This directive controls the total amount of RAM
              which can maximally be used for cached RAM files.
              The default value is 1000000, 1 megabyte.

\item \verb+max_size_cached_file = Integer+ ---
              This directive sets a maximum size on the files
              that are RAM cached by \Yaws{}. The default value is
              8000 bytes.

\item \verb+cache_refresh_secs = Integer+ ---
              The RAM cache is used to serve pages that sit in
              the cache. An entry sits in cache at most
              cache\_refresh\_secs number of seconds. The default
              is 30. This means that when the content is updated
              under the docroot, that change doesn't show until
              30 seconds have passed. While developing a \Yaws\
              site, it may be convenient to set this value to 0.
              If the debug flag (\textit{-d}) is passed to the
              \Yaws\ start script, this value is automatically set
              to 0.

\item \verb+trace = traffic | http+ ---
              This enables traffic or HTTP tracing. Tracing is
              also possible to enable with a command line flag to
              \Yaws{}.

\item \verb+use_old_ssl = true | false+ ---
              This re-enables the old OTP ssl implementation. By default we use
              the new ssl implementation.

\item \verb+auth_log = true | false+ ---
              \textit{Deprecated and ignored. Now, this target must be set in
                server part}.

\item \verb+max_connections = nolimit | Integer+ ---
              This value controls the maximum number of connections
              from HTTP clients into the server. This is implemented
              by closing the last socket if the threshold is reached.

\item \verb+keepalive_maxuses = nolimit | Integer+ ---
              Normally, \Yaws\ does not restrict the number of times a
              connection is kept alive using keepalive. Setting this
              parameter to an integer \verb+X+ will ensure that
              connections are closed once they have been used \verb+X+
              times. This can be a useful to guard against
              long-running connections collecting too much garbage in
              the \Erlang\ VM.

\item \verb+process_options = undefined | Proplist+ ---
              Set process spawn options for client acceptor processes.
              Options must be specified as a quoted string of either
              the atom \verb+undefined+ or as a proplist of valid
              process options. The supported options are
              \verb+fullsweep_after+, \verb+min_heap_size+, and
              \verb+min_bin_vheap_size+, each taking an associated
              integer value. Other process options are ignored. The
              proplist may also be empty. See
              \verb+erlang:spawn_opt/4+ for details on these options.

\item \verb+acceptor_pool_size = Integer+ ---
              Set the size of the pool of cached acceptor
              processes. The specified value must be greater than or
              equal to 0. The default value is 8. Specifying a value
              of 0 effectively disables the process pool.

\item \verb+log_wrap_size = Integer+ ---
              The logs written by \Yaws\ are all wrap logs, the default value at
              the size where they wrap around and the original gets renamed to
              File.old is 1000000, 1 megabyte. This value can changed.


              If we set the value to 0 the logs will never wrap. If we want to
              use \Yaws\ in combination with a more traditional log wrapper such
              as logrotate, set the size to 0 and \Yaws\ will reopen the
              logfiles once they have be renamed/removed.

\item \verb+log_resolve_hostname = true | false+ ---
              By default the client host IP is not resolved in the access logs.

\item \verb+fail_on_bind_err = true | false+ ---
              Fail completely or not if \Yaws\ fails to bind a listen socket
              Default is true.

\item \verb+soap_srv_mods = ListOfModuleSetting+ ---
              If \verb+enable_soap+ is true, a startup \Yaws\ will invoke
              \verb+yaws_soap_srv:setup()+ to setup modules set
              here. \verb+ModuleSetting+ is either a triad like\\
              \verb+<Mod, HandlerFun, WsdlFile>+ or a tetrad like
              \verb+<Mod, HandlerFun, WsdlFile, Prefix>+\\ which specifies the
              prefix. A prefix will be used as argument of
              \verb+yaws_soap_lib:initModel()+ and then be used as a XML
              namespace prefix. Note, the WsdlFile here should be an
              absolute-path file in local file systems.

              For example, we can specify
\begin{verbatim}
  soap_srv_mods=<Mod1,Handler,WsdlFile1> <Mod2,Handler,Wsdl2,SpecifiedPrefix>
\end{verbatim}

\item \verb+php_exe_path = Path+ ---
              \textit{this target is deprecated and useless. use 'php\_handler'
                target in server part instead}.

              The name of (and possibly path to) the php executable used to
              interpret php scripts (if allowed). Default is php-cgi.

\item \verb+copy_error_log = true | false+ ---
              Enable or disable copying of the error log. When we run in
              embedded mode, there may very well be some other systems process
              that is responsible for writing the errorlog to a file whereas
              when we run in normal standalone mode, we typically want the
              Erlang errorlog written to a report.log file. Default value is
              true.

\item \verb+ysession_mod = Module+ ---
               Allows to specify a different \Yaws\ session storage mechanism
               instead of an ETS table. One of the drawbacks of the default
               \verb+yaws_session_server+ implementation is that server side
               cookies are lost when the server restarts. Specifying a different
               module here will pass all writes/read operations to this module
               (it must implements appropriate callbacks).

\item \verb+runmod = ModuleName+ ---
               At startup \Yaws\ will invoke \verb+ModuleName:start()+ in a
               separate process. It is possible to have several runmods. This
               is useful if we want to reuse the Yaws startup shell script for
               our own application.

\item \verb+pick_first_virthost_on_nomatch = true | false+ ---
              When \Yaws\ gets a request, it extracts the Host: header from the
              client request to choose a virtual server amongst all servers with
              the same IP/Port pair. This configuration parameter decides
              whether Yaws should pick the first (as defined in the yaws.conf
              file) if no name match or not. In real live hosting scenarios we
              typically want this to be false whereas in testing/development
              scenarios it may be convenient to set it to true. Default is true.


\item \verb+keepalive_timeout = Integer | infinity+ ---
              If the HTTP session will be kept alive (i.e., not
              immediately closed) it will close after the specified
              number of milliseconds unless a new request is received
              in that time. The default value is 30000. The value
              \verb+infinity+ is legal but not recommended.

\item \verb+subconfig = File+ ---
              Load specified config file.

\item \verb+subconfigdir = Directory+ ---
              Load all config files in specified directory.

\item \verb+x_forwarded_for_log_proxy_whitelist = ListOfUpstreamProxyServerIps+ ---
              \textit{This target is deprecated and will be ignored}.

\end{itemize}



\section{Server Part}

\Yaws\ can virthost several web servers on the same IP address as well
as several web servers on different IP addresses. The only limitation
here is that there can be only one server with SSL enabled per each
individual IP address. Each virtual host is defined within a matching
pair of \verb+<server ServerName>+ and \verb+</server>+. The
\verb+ServerName+ will be the name of the web server.

The following directives are allowed inside a server definition.

\begin{itemize}

\item \verb+port = Port+ ---
              This makes the server listen on Port. Default is 8000.

\item \verb+listen = IpAddress+ ---
              This makes the server listen on \verb+IpAddress+ when
              virthosting several servers on the same IP/port
              address, if the browser doesn't send a \verb+Host:+ field,
              \Yaws\ will pick the first server specified in the
              config file. Multiple \verb+listen+ directives may be
              used to specify several addresses to listen on.

\item \verb+listen_backlog = Integer+ ---
              This sets the TCP listen backlog for the server to
              define the maximum length the queue of pending
              connections may grow to. The default is the same as
              the default provided by \verb+gen_tcp:listen/2+, which
              is 5.

\item \verb+server_signature = String+ ---
              This directive sets the "Server: " output header to the custom
              value and overloads the global one for this virtual server.

\item \verb+rhost = Host[:Port]+ ---
             This forces all local redirects issued by the server to go to Host.
             This is useful when \Yaws\ listens to a port which is different
             from the port that the user connects to. For example, running
             \Yaws\ as a non-privileged user makes it impossible to listen to
             port 80, since that port can only be opened by a privileged
             user. Instead \Yaws\ listens to a high port number port, 8000, and
             iptables are used to redirect traffic to port 80 to port 8000 (most
             NAT:ing firewalls will also do this for you).

\item \verb+rscheme = http | https+ ---
              This forces all local redirects issued by the
              server to use this method. This is useful when an
              SSL off-loader, or stunnel, is used in front of
              \Yaws{}.

\item \verb+auth_log = true | false+ ---
              Enable or disable the auth log for this virtual server.
              Default is true.

\item \verb+access_log = true | false+ ---
              Setting this directive to false turns off
              traffic logging for this virtual server. The
              default value is true.

\item \verb+logger_mod = Module+ ---
              It is possible to set a special module that handles access and
              auth logging. The default is to log all web server traffic to
              \verb+<Host>.access+ and \verb+<Host>.auth+ files in the
              configured or default \verb+logdir+.

              This module must implement the behaviour
              \verb+yaws_logger+. Default value is \verb+yaws_log+.

              The following functions should be exported:

              \begin{itemize}

              \item \verb+Module:open_log(ServerName, Type, LogDir)+ --- When
                \Yaws\ is started, this function is called for this virtual
                server. If the initialization is successful, the function must
                return \verb+{true, State}+ and if an error occurred, it must
                return \verb+false+.

              \item \verb+Module:close_log(ServerName, Type, State)+ -- This
                function is called for this virtual server when
                \Yaws\ is stopped.

              \item \verb+Module:wrap_log(ServerName, Type, State, LogWrapSize)+
                --- This function is used to rotate log files. It is regularly
                called by \Yaws\ and must return the possibly updated internal
                \verb+NewState+.

              \item \verb+Module:write_log(ServerName, Type, State, Infos)+ --
                When it needs to log a message, \Yaws\ will call this
                function. The parameter \verb+Infos+ is
                \verb+{Ip, Req, InHdrs, OutHdrs, Time}+ for an access log and
                \verb+{Ip, Path, Item}+ for an auth log, where:

                      \begin{itemize}
                      \item \verb+Ip+ --- IP address of the accessing client (as
                        a tuple).

                      \item \verb+Req+ --- The HTTP method, URI path, and HTTP
                        version of the request (as an\\ \verb+#http_request{}+
                        record).

                      \item \verb+InHdrs+ --- The HTTP headers which were sent
                        from the WWW client (as a \verb+#headers{}+ record).

                      \item \verb+OutHdrs+ --- The HTTP headers sent to the WWW
                        client (as a \verb+#outh{}+ record).

                      \item \verb+Path+ --- The URI path of the request (as a
                        string).

                      \item \verb+Item+ -- The result of an authentication
                        request. May be \verb+{ok, User}+, \verb+403+ or\\
                        \verb+{401, Realm}+.

                      \item \verb+Time+ --- The time taken to serve the request,
                        in microseconds.
                      \end{itemize}

              For all of these callbacks, \verb+ServerName+ is the virtual
              server's name, \verb+Type+ is the atom \verb+access+ or
              \verb+auth+ and \verb+State+ is the internal state of the logger.

              \end{itemize}

\item \verb+shaper = Module+ ---
              Defines a module to control access to this virtual server.

              Access can be controlled based on the IP address of the client. It
              is also possible to throttle HTTP requests based on the client's
              download rate. This module must implement the behaviour
              \verb+yaws_shaper+.

              There is no such module configured by default.

\item \verb+dir_listings = true | true_nozip | false+ ---
             Setting this directive to false disallows the automatic dir listing
             feature of \Yaws{}. A status code 403 Forbidden will be sent. Set
             to true\_nozip to avoid the auto-generated all.zip entries. Default
             is false.

\item \verb+extra_cgi_vars = .....+ ---
             Add additional CGI or FastCGI variables. For example:
\begin{verbatim}
  <extra_cgi_vars dir='/path/to/some/scripts'>
    var = val
    ...
  </extra_cgi_vars>
\end{verbatim}

\item \verb+statistics = true | false+ ---
             Turns on/off statistics gathering for a virtual server. Default is
             false.

\item \verb+fcgi_app_server = Host:Port+ ---
             The hostname and TCP port number of a FastCGI application
             server. The TCP port number is not optional. There is no default
             value.

\item \verb+fcgi_trace_protocol = true | false+ ---
             Enable or disable tracing of FastCGI protocol messages as info log
             messages. Disabled by default.

\item \verb+fcgi_log_app_error = true | false+ ---
             Enable or disable logging of application error messages (output to
             stderr and non-zero exit value). Disabled by default.

\item \verb+deflate = true | false+ ---
             Turns on or off deflate compression for a server. Default is
             false.

\item \verb+<deflate> ... </deflate>+ ---
             This begins and ends the deflate compression configuration for this
             server. The following items are allowed within a matching pair of
             <deflate> and </deflate> delimiters.

             \begin{itemize}
             \item \verb+min_compress_size = nolimit | Integer+ --- Defines the
               smallest response size that will be compressed. If nolimit is not
               used, the specified value must be strictly positive. The default
               value is nolimit.

             \item \verb+compress_level = none | default | best_compression | best_speed | 0..9+ ---\\
               Defines the compression level to be used. 0 (none), gives no
               compression at all, 1 (best\_speed) gives best speed and 9
               (best\_compression) gives best compression. The default value is
               default.

             \item \verb+window_size = 9..15+ --- Specifies the zlib compression
               window size. It should be in the range 9 through 15. Larger
               values of this parameter result in better compression at the
               expense of memory usage. The default value is 15.

             \item \verb+mem_level = 1..9+ --- Specifies how much memory should
               be allocated for the internal compression
               state. \verb+mem_level=1+ uses minimum memory but is slow and
               reduces compression ratio; \verb+mem_level=9+ uses maximum memory
               for optimal speed. The default value is 8.

             \item \verb+strategy = default | filtered | huffman_only+ --- This
               parameter is used to tune the compression algorithm. See
               \verb+zlib(3erl)+ for more details on the \verb+strategy+
               parameter. The default value is default.

             \item \verb+use_gzip_static = true | false+ --- If true,
               \Yaws\ will try to serve precompressed versions of static
               files. It will look for precompressed files in the same location
               as original files that end in ".gz". Only files that do not fit
               in the cache are concerned. The default value is false.

             \item \verb+mime_types = ListOfTypes | defaults | all+ ---
               Restricts the deflate compression to particular MIME types. The
               special value all enable it for all types (It is a synonym of
               `*/*'). MIME types into \verb+ListOfTypes+ must have the form
               `type/subtype' or `type/*' (indicating all subtypes of that
               type). Here is an example:
\begin{verbatim}
  mime_types = default image/*
  mime_types = application/xml application/xhtml+xml application/rss+xml
\end{verbatim}
                    By default, the following MIME types are compressed (if
                    \verb+deflate+ is set to true):

                    \begin{itemize}
                    \item \verb+text/*+
                    \item \verb+application/rtf+
                    \item \verb+application/msword+
                    \item \verb+application/pdf+
                    \item \verb+application/x-dvi+
                    \item \verb+application/javascript+
                    \item \verb+application/x-javascript+
                    \end{itemize}
                    Multiple \verb+mime_types+ directive can be used.
             \end{itemize}

\item \verb+docroot = Directory ...+ ---
              This makes the server serve all its content from
              \verb+Directory+.

              It is possible to pass a space-separated list of directories as
              docroot. If this is the case, the various directories will be
              searched in order for the requested file. This also works with the
              ssi and yssi constructs where the full list of directories will be
              searched for files to ssi/yssi include. Multiple docroot
              directives can be used. You need at least one valid docroot,
              other invalid docroots are skipped with their associated auth
              structures.

\item \verb+auth_skip_docroot = true | false+ ---
              If true, the docroot will not be searched for
              \verb+.yaws_auth+ files. This is useful when the
              docroot is quite large and the time to search it is
              prohibitive when \Yaws\ starts up. Defaults to false.

\item \verb+partial_post_size = Integer+ ---
              When a \Yaws\ file receives large \verb+POST+s, the
              amount of data received in each chunk is
              determined by the this parameter. The default
              value is 10240.

\item \verb+dav = true | false+ ---
              Turns on the DAV protocol for this server. The dav support in
              \Yaws\ is highly limited. If dav is turned on, .yaws processing of
              .yaws pages is turned off. Default is false. Setting it to nolimit
              is potentially dangerous. The socket read timeout is supplied by
              the keepalive\_timeout setting. If the read is not done within the
              timeout, the POST will fail.

\item \verb+tilde_expand = true|false+ ---
              If this value is set to false \Yaws\ will
              never do tilde expansion. Tilde expansion takes a URL
              of the form
              \verb+http://www.foo.com/+\char`\~\verb+username+ and
              changes it into a request where the docroot for that
              particular request is set to the directory
              \char`\~\verb+username/public_html/+. The default value
              is false.

\item \verb+allowed_scripts = ListOfSuffixes+ ---
              The allowed script types for this server. Recognized are
              \textit{yaws}, \textit{cgi}, \textit{fcgi}, \textit{php}. Default
              is \verb+allowed_scripts = yaws php cgi fcgi+.

\item \verb+tilde_allowed_scripts = ListOfSuffixes+ ---
             The allowed script types for this server when executing files in a
             users \verb+public_html+ folder Recognized are \textit{yaws},
             \textit{cgi}, \textit{fcgi}, \textit{php}. Default is\\
             \verb+tilde_allowed_scripts =+ (i.e., empty).

\item \verb+appmods = ListOfModuleNames+ ---
             If any the names in \verb+ListOfModuleNames+ appear as components
             in the path for a request, the path request parsing will terminate
             and that module will be called. There is also an alternate syntax
             for specifying the appmods if we don't want our internal erlang
             module names to be exposed in the URL paths. We can specify
\begin{verbatim}
  appmods = <Path1, Module1> <Path2, Modules2> ...
\end{verbatim}
             Assume for example that we have the URL
             \url{http://www.hyber.org/myapp/foo/bar?user=joe} while we
             have the module \verb+foo+ defined as an appmod, the function
             \verb+foo:out(Arg)+ will be invoked instead of searching the
             filesystems below the point \verb+foo+.

             The \verb+Arg+ argument will have the missing path part supplied in
             its \verb+appmoddata+ field.

             It is also possible to exclude certain directories from appmod
             processing. This is particulaly interesting for '/' appmods. Here
             is an example:
\begin{verbatim}
  appmods = </, myapp exclude_paths icons js top/static>
\end{verbatim}
             The above configuration will invoke the \verb+myapp+ erlang module
             on everything except any file found in directories \verb+icons+,
             \verb+js+ and \verb+top/static+ relative to the docroot.

\item \verb+errormod_404 = Module+ ---
              It is possible to set a special module that handles 404 Not Found
              messages. The function\\ \verb+Module:out404(Arg, GC, SC)+ will be
              invoked. The arguments are
              \begin{itemize}
              \item \verb+Arg+ --- a \verb+#arg{}+ record
              \item \verb+GC+ --- a \verb+#gconf{}+ record (defined in yaws.hrl)
              \item \verb+SC+ --- a \verb+#sconf{}+ record (defined in yaws.hrl)
              \end{itemize}
              The function can and must do the same things that a normal
              \verb+out/1+ does.

\item \verb+errormod_401 = Module+ ---
              It is possible to set a special module that handles 401
              Unauthorized messages. This can for example be used to display a
              login page instead. The function \\
              \verb+Module:out401(Arg, Auth, Realm)+ will be invoked. The
              arguments are
              \begin{itemize}
              \item \verb+Arg+ --- a \verb+#arg{}+ record
              \item \verb+Auth+ --- a \verb+#auth{}+ record
              \item \verb+Realm+ --- a string
              \end{itemize}
              The function can and must do the same things that a normal
              \verb+out/1+ does.

\item \verb+errormod_crash = Module+ ---
              It is possible to set a special module that handles the HTML
              generation of server crash messages. The default is to display the
              entire formated crash message in the browser. This is good for
              debugging but not in production.

              The function \verb+Module:crashmsg(Arg, SC, Str)+ will be
              called. The \verb+Str+ is the real crash message formated as a
              string.

              The function must return, \verb+{content,MimeType,Cont}+ or
              \verb+{html, Str}+ or \verb+{ehtml, Term}+. That data will be
              shipped to the client.

\item \verb+expires = ListOfExpires+ ---
              Controls the setting of the \verb+Expires+ HTTP header and the
              \verb+max-age+ directive of the \verb+Cache-Control+ HTTP header
              in server responses for specific MIME types. The expiration date
              can set to be relative to either the time the source file was last
              modified, or to the time of the client
              access. \verb+ListOfExpires+ is defined as follows:
\begin{verbatim}
  expires = <MimeType1, access+Seconds> <MimeType2, modify+Seconds> ...
\end{verbatim}
              These HTTP headers are an instruction to the client about the
              document's validity and persistence. If cached, the document may
              be fetched from the cache rather than from the source until this
              time has passed. After that, the cache copy is considered
              "expired" and invalid, and a new copy must be obtained from the
              source.
              Here is an example:
\begin{verbatim}
  expires = <image/gif, access+2592000> <image/png, access+2592000>
  expires = <image/jpeg, access+2592000> <text/css, access+2592000>
\end{verbatim}

\item \verb+arg_rewrite_mod = Module+ ---
              It is possible to install a module that rewrites all the
              \verb+Arg+ \verb+#arg{}+ records at an early stage in the
              \Yaws\ server. This can be used to do various things such as
              checking a cookie, rewriting paths etc.

              The module \verb+yaws_vdir+ can be used in case you want to serve
              static content that is not located in your docroot. See the
              example at the bottom of this man page for how to use the
              \verb+opaque+ + \verb+vdir+ elements to instruct the
              \verb+yaws_vdir+ module what paths to rewrite.

\item \verb+start_mod = Module+ ---
              Defines a user-provided callback module. At startup of the server,\\
              \verb+Module:start/1+ will be called. The \verb+#sconf{}+ record
              (defined in \verb+yaws.hrl+) will be used as the input argument. This
              makes it possible for a user application to synchronize the
              startup with the \Yaws\ server as well as getting hold of user
              specific configuration data, see the explanation for the
              \verb+<opaque>+ context.

\item \verb+revproxy = Prefix Url [intercept_mod Module]+ ---
              Make \Yaws\ a reverse proxy. \verb+Prefix+ is a path inside our own
              docroot and \verb+Url+ is a URL pointing to a website we
              want to "mount" under the \verb+Prefix+ path. For example:

              \verb+revproxy = /tmp/foo http://yaws.hyber.org+

              This makes the hyber website appear under \verb+/tmp/foo+.

              It is possible to have multiple reverse proxies inside the same
              server by supplying multiple \verb+revproxy+ directives.

              If the optional keyword \verb+intercept_mod+ and
              \verb+Module+ are supplied in the \verb+revproxy+ directive,
              then \verb+Module+ indicates a proxy request and response
              interception module. When the reverse proxy receives a
              request from a client, it will first pass
              \verb+#http_request{}+ and \verb+#headers{}+ records
              representing the client request to the intercept module's
              \verb+rewrite_request/2+ function. The function must return a
              3-tuple of the following form:

\begin{verbatim}
{ok, #http_request{}, #headers{}}
\end{verbatim}

              where the record instances can be the original values passed
              in or new values. The reverse proxy will use these record
              instances when passing the request to the backend server.

              Similarly, when the backend server returns a response, the
              reverse proxy will call the intercept module's
              \verb+rewrite_response/2+ function, passing it an
              \verb+#http_response{}+ record and a \verb+#headers{}+
              record. The function must return a 3-tuple of the following
              form:

\begin{verbatim}
{ok, #http_response{}, #headers{}}
\end{verbatim}

              where the record instances can be the original values passed
              in or new values. The reverse proxy will use these record
              instances when returning the response to the client.

              Any failure within an intercept module function results in
              HTTP status code 500 (Internal Server Error) being returned
              to the client.

              Intercept modules can use the following functions from the
              \verb+yaws_api+ module to retrieve, set, or delete HTTP
              headers from \verb+#headers{}+ records:

\begin{itemize}
\item \verb+set_header/2+, \verb+set_header/3+
\item \verb+get_header/2+, \verb+get_header/3+
\item \verb+delete_header/2+
\end{itemize}

\item \verb+fwdproxy = true|false+ ---
              Make \Yaws\ a forward proxy. By enabling this option you can use
              \Yaws\ as a proxy for outgoing web traffic, typically by
              configuring the proxy settings in a web-browser to explicitly
              target \Yaws\ as its proxy server.

\item \verb+servername = Name+ ---
              If we're virthosting several servers and want to force a server to
              match specific \verb+Host:+ headers we can do this with the \verb+servername+
              directive. This name doesn't necessarily have to be the same as
              the name inside \verb+<server Name>+ in certain NAT scenarios. Rarely
              used feature.

\item \verb+php_handler+ ---
              Set handler to interpret \textit{.php} files. It can be
              one of the following definitions:

              \begin{itemize}
              \item \verb+php_handler = <cgi, Filename>+ --- The name
                of (and possibly path to) the PHP executable used to
                interpret PHP scripts (if allowed).
              \item \verb+php_handler = <fcgi, Host:Port>+ --- Use the
                specified FastCGI server to interpret \textit{.php}
                files (if allowed).

                \Yaws\ does not start the PHP interpreter in FastCGI
                mode for you. To run PHP in FastCGI mode, call it with
                the \textit{-b} option. For example:
\begin{verbatim}
  php5-cgi -b '127.0.0.1:54321'
\end{verbatim}
                This starts PHP5 in FastCGI mode listening on the local
                network interface. To make use of this PHP server from
                \Yaws{}, specify:
\begin{verbatim}
  php_handler = <fcgi, 127.0.0.1:54321>
\end{verbatim}
                The PHP interpreter needs read access to the files it
                is to serve. Thus, if you run it in a different
                security context than \Yaws\ itself, make sure it has
                access to the \textit{.php} files.

                Please note that anyone who is able to connect to the PHP
                FastCGI server directly can use it to read any file to
                which it has read access. You should consider this
                when setting up a system with several mutually
                untrusted instances of PHP.

              \item \verb+php_handler = <extern, Module:Function | Node:Module:Function>+
                --- Use an external handler, possibly on another node, to
                interpret \textit{.php} files (if allowed).

                To interpret a \textit{.php} file, the function
                \verb+Module:Function(Arg)+ will be invoked (evaluated
                inside an rpc call if a \verb+Node+ is specified),
                where \verb+Arg+ is a \verb+#arg{}+ record.

                The function must do the same things that a normal
                \verb+out/1+ does.

              \end{itemize}
              Default value is \verb+<cgi, "/usr/bin/php-cgi">+.

\item \verb+phpfcgi = HostPortSpec+ ---
              \textit{this target is deprecated. use php\_handler target in
                server part instead}.

              Use this directive is same as:
              \verb+php_handler = <fcgi, HostPortSpec>+.

\item \verb+<ssl> .... </ssl>+
               This begins and ends an SSL configuration for this server. It's
               possible to virthost several SSL servers on the same IP given
               that they all share the same certificate configuration. In
               general it is complicated to virthost several SSL servers on the
               same IP address since the certificate is typically bound to a
               domainname in the common name part of the certificate. One
               solution (the only?) to this problem is to have a certificate
               with multiple subjectAltNames. See
               \url{http://wiki.cacert.org/VhostTaskForce#Interoperability_Test}

               \begin{itemize}
               \item \verb+keyfile = File+ --- Specifies which file contains the
                 private key for the certificate.

               \item \verb+certfile = File+ --- Specifies which file contains
                 the certificate for the server.

               \item \verb+cacertfile = File+ --- A file containing trusted
                 certificates to use during client authentication and to use
                 when attempting to build the server certificate chain. The list
                 is also used in the list of acceptable client CAs passed to the
                 client when a certificate is requested.

               \item \verb+verify = 0 | 1 | 2 | verify_none | verify_peer+ ---
                 Specifies the level of verification the server does on client
                 certs. 0 means that the server will not ask for a cert
                 (\verb+verify_none+), 1 means that the server will ask the
                 client for a cert but not fail if the client does not supply a
                 client cert (\verb+verify_peer+, \verb+fail_if_no_peer_cert+ =
                 \verb+false+), 2 means that the server requires the client to
                 supply a client cert (\verb+verify_peer+,
                 \verb+fail_if_no_peer_cert+ = \verb+true+).

                 Setting \verb+verify_none+ means that the x509 validation will
                 be skipped (no certificate request is sent to the client),
                 \verb+verify_peer+ means that a certificate request is sent to
                 the client (x509 validation is performed.

                 You might want to use \verb+fail_if_no_peer_cert+ in
                 combination with \verb+verify_peer+.

               \item \verb+fail_if_no_peer_cert = true | false+ --- If verify is
                 set to \verb+verify_peer+ and set to \verb+true+ the connection
                 will fail if the client does not send a certificate (i.e. an
                 empty certificate). If set to false the server will fail only
                 if an invalid certificate is supplied (an empty certificate is
                 considered valid).

               \item \verb+depth = Int+ --- Specifies the depth of certificate
                 chains the server is prepared to follow when verifying client
                 certs. For the OTP new ssl implementation it is also used to
                 specify how far the server, i.e. we, shall follow the SSL
                 certificates we present to the clients. Hence, using self
                 signed certs, we typically need to set this to 0.

               \item \verb+password = String+ --- If the private key is
                 encrypted on disk, this password is the 3des key to decrypt it.

               \item \verb+ciphers = String+ --- This string specifies the SSL
                 cipher string. The syntax of the SSL cipher string is a little
                 horrible sub-language of its own. It is documented in the SSL
                 man page for "ciphers".
               \end{itemize}

\item \verb+<redirect> ... </redirect>+ ---
              Defines a redirect mapping. The following items are allowed within
              a matching pair of \verb+<redirect>+ and \verb+</redirect>+ delimiters.

              We can have a series of \verb+Path = URL+ or \verb+Path = file+

              All accesses to \verb+Path+ will be redirected to \verb+URL/Path+
              or to \verb+scheme:host:port/file/Path+ if a file is
              used. Note that the original path is appended to the redirected
              url. So if we for example have:
\begin{verbatim}
  <redirect>
    /foo = http://www.mysite.org/zapp
    /bar = /tomato.html
  </redirect>
\end{verbatim}
              Assuming this config resides on a site called
              \url{http://abc.com}, We have the following redirects:
\begin{verbatim}
  http://abc.com/foo -> http://www.mysite.org/zapp/foo

  http://abc.com/foo/test -> http://www.mysite.org/zapp/foo/test

  http://abc.com/bar -> http://abc.com/bar

  http://abc.com/bar/x/y/z -> http://abc.com/bar/x/y/z
\end{verbatim}
              Sometimes we do not want to have the original path appended to the
              redirected path. To get that behaviour we specify the config with
              '==' instead of '='.
\begin{verbatim}
  <redirect>
    /foo == http://www.mysite.org/zapp
    /bar = /tomato.html
  </redirect>
\end{verbatim}
              With this configuration, a request for
              \url{http://abc.com/foo/x/y/z} simply gets redirected to
              \url{http://www.mysite.org/zapp}. This is typically used when
              we simply want a static redirect at some place in the
              docroot.

              When we specify a file as target for the redirect, the redir will
              be to the current http(s) server.

\item \verb+<auth> ... </auth>+ ---
              Defines an auth structure. The following items are allowed within
              a matching pair of <auth> and </auth> delimiters.

              \begin{itemize}
              \item \verb+docroot = Docroot+ --- If a \verb+Docroot+ is defined,
                this auth structure will be tested only for requests in the
                specified docroot. No docroot configured means all docroots. If
                two auth structures are defined, one with a docroot and one with
                no docroot, the first of both overrides the second one for
                requests in the configured docroot.

              \item \verb+dir = Dir+ --- Makes \verb+Dir+ to be controlled by
                WWW\-authenticate headers. In order for a user to have access to
                WWW\-Authenticate controlled directory, the user must supply a
                password. The \verb+Dir+ must be specified relative to the
                docroot. Multiple dir can be used. If no dir is set, the default
                value, "/", will be used.

              \item \verb+realm = Realm+ --- In the directory defined here, the
                WWW-Authenticate Realm is set to this value.

              \item \verb+authmod = AuthMod+ --- If an \verb+AuthMod+ is defined
                then \verb+AuthMod:auth(Arg, Auth)+ will be called for all
                access to the directory. The \verb+auth/2+ function should
                return one of: \verb+true+, \verb+false+, \verb+{false, Realm}+,
                \verb+{appmod, Mod}+. If \verb+{appmod, Mod}+ is returned then a
                call to\\ \verb+Mod:out401(Arg, Auth, Realm)+ will be used to
                deliver the content. If \verb+errormod_401+ is defined, the call
                to \verb+Mod+ will be ignored. (\verb+Mod:out(Arg)+ is
                deprecated).

                This can, for example, be used to implement cookie
                authentication. The \verb+auth()+ callback would check if a
                valid cookie header is present, if not it would return
                \verb+{appmod, ?MODULE}+ and the \verb+out401/1+ function in the
                same module would return \verb+{redirect_local, "/login.html"}+.

              \item \verb+user = User:Password+ --- Inside this directory, the
                user \verb+User+ has access if the user supplies the password
                \verb+Password+ in the popup dialogue presented by the browser.
                We can obviously have several of these value inside a single
                <auth> </auth> pair.

                The usage of User:Password in the actual config file is
                deprecated as of release 1.51. It is preferred to have the users
                in a file called \verb+.yaws_auth+ in the actual directory. The
                \verb+.yaws_auth+ file has to be file parseable by
                \verb+file:consult/1+.

                Each row of the file must contain terms on the form.

              \item \verb+pam service = pam-service+ --- If the item \verb+pam+
                is part of the auth structure, Yaws will also try to
                authenticate the user using "pam" using the pam \verb+service+
                indicated. Usual services are typically found under
                /etc/pam.d. Usual values are "system-auth" etc.

                pam authentication is performed by an Erlang port program which
                is typically installed as suid root by the Yaws install script.

              \item \verb+allow = all | ListOfHost+ --- The \verb+allow+
                directive affects which hosts can access an area of the
                server. Access can be controlled by IP address or IP address
                range. If all is specified, then all hosts are allowed access,
                subject to the configuration of the \verb+deny+ and \verb+order+
                directives. To allow only particular hosts or groups of hosts to
                access the server, the host can be specified in any of the
                following formats:

                A full IP address
\begin{verbatim}
  allow = 10.1.2.3
  allow = 192.168.1.104, 192.168.1.205
\end{verbatim}
                network/netmask pair
\begin{verbatim}
  allow = 10.1.0.0/255.255.0.0
\end{verbatim}
                network/nnn CIDR specification
\begin{verbatim}
  allow = 10.1.0.0/16
\end{verbatim}

              \item \verb+deny = all | ListOfHost+ --- This directive allows
                access to the server to be restricted based on IP address. The
                arguments for the \verb+deny+ directive are identical to the
                arguments for the \verb+allow+ directive.

              \item \verb+order = Ordering+ --- The \verb+order+ directive,
                along with \verb+allow+ and \verb+deny+ directives, controls a
                three-pass access control system. The first pass processes
                either all \verb+allow+ or all \verb+deny+ directives, as
                specified by the \verb+order+ directive. The second pass parses
                the rest of the directives (\verb+deny+ or \verb+allow+). The
                third pass applies to all requests which do not match either of
                the first two.

                Ordering is one of (Default value is \verb+deny,allow+):
                \begin{itemize}
                  \item \verb+allow,deny+ --- First, all \verb+allow+ directives
                    are evaluated; at least one must match, or the request is
                    rejected. Next, \verb+deny+ directives are evaluated. If any
                    matches, the request is rejected. Last, any requests which
                    do not match an \verb+allow+ or a \verb+deny+ directive are
                    denied by default.

                  \item \verb+deny,allaw+ --- First, all \verb+deny+ directives
                    are evaluated; if any match, the request is denied unless it
                    also matches an \verb+allow+ directive. Any requests which
                    do not match any \verb+allow+ or \verb+deny+ directives are
                    permitted.
                \end{itemize}
              \end{itemize}

\item \verb+<opaque> ... </opaque>+ ---
              This begins and ends an opaque configuration context for this
              server, where '\verb+Key = Value+' directives can be
              specified. These directives are ignored by \Yaws\ (hence the name
              opaque), but can be accessed as a list of tuples
              \verb+{Key,Value}+ stored in the \verb+#sconf.opaque+ record
              entry. See also the description of the \verb+start_mod+ directive.

              This mechanism can be used to pass data from a surrounding
              application into the individual .yaws pages.
\end{itemize}




\section{Configuration Examples}

       The following example defines a single server on
       port 80.

\begin{verbatim}
       logdir = /var/log/yaws
       <server www.mydomain.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www
       </server>
\end{verbatim}

       And this example shows a similar setup but two web
       servers on the same IP address:

\begin{verbatim}
       logdir = /var/log/yaws
       <server www.mydomain.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www
       </server>

       <server www.funky.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www_funky_org
       </server>
\end{verbatim}


When there are several virtual hosts defined for the same IP number
and port, and an HTTP request arrives with a \verb+Host+ field that
does not match any defined virtual host, then the one which defined
``first'' in the file is chosen.

An example with www-authenticate and no access logging at all.

\begin{verbatim}
       logdir = /var/log/yaws
       <server www.mydomain.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www
               access_log = false
               <auth>
                   dir = /var/yaws/www/secret
                   realm = foobar
                   user = jonny:verysecretpwd
                   user = benny:thequestion
                   user = ronny:havinganamethatendswithy
              </auth>

       </server>
\end{verbatim}

       And finally a slightly more complex example with
       two servers on the same IP, and one SSL server on a
       different IP.

       The \verb+is_default+ is used to select the funky server if
       someone types in for example url{http://192.168.128.31/} in
       his\slash her browser.


\begin{verbatim}
       logdir = /var/log/yaws
       max_num_cached_files = 8000
       max_num_cached_bytes = 6000000

       <server www.mydomain.org>
               port = 80
               listen = 192.168.128.31
               docroot = /var/yaws/www
       </server>

       <server www.funky.org>
               port = 80
               is_default = true
               listen = 192.168.128.31
               docroot = /var/yaws/www_funky_org
       </server>

       <server www.funky.org>
               port = 443
               listen = 192.168.128.32
               docroot = /var/yaws/www_funky_org
               <ssl>
                  keyfile = /etc/funky.key
                  certfile = /etc/funky.cert
                  password = gazonk
               </ssl>
       </server>
\end{verbatim}

\chapter{WebSocket Protocol Support}
\label{websockets}

\Yaws\ supports the WebSocket Protocol (RFC 6455), which enables
two-way communication between clients and web servers. \Yaws\ also
provides support for working drafts of the WebSocket protocol,
specifically drafts 10 to 17 of the hybi working group. No support for
other drafts, such as those from the hixie working group, is provided.

You can find example usage of the WebSocket Protocol in the file
\verb+www/websockets_example.yaws+. This example, intended for use
with any browser supporting RFC 6455, returns HTML and JavaScript that
allow the client to establish a WebSocket connection to the
server. These connections are handled by the code in
\verb+www/websockets_example_endpoint.yaws+, which when invoked simply
establishes \\ \verb+examples/src/basic_echo_callback.erl+ as the
WebSocket callback module for the connection.

\section{WebSocket Callback Modules}

A WebSocket callback module implements either the
\verb+handle_message/1+ callback function or the
\\ \verb+handle_message/2+ callback function, depending on whether
it's a basic or advanced callback module.

\subsection{Basic Callback Modules}

The argument passed to \verb+handle_message/1+ callback function takes
one of the following forms:

\begin{itemize}

\item \verb+{text, Text}+ --- the callback receives an unfragmented
  text message.

\item \verb+{binary, Message}+ --- the callback receives an
  unfragmented binary message.

\item \verb+{close, Status, Reason}+ --- the callback receives a
  notification that the client has closed the socket. \verb+Status+ is the
  numerical status code sent by the client or the value 1000 (as suggested
  by RFC 6455 section 7.4.1) if the client sent no status code. For an
  abnormal client closure, the status code is 1006 (as specified by RFC
  6455 section 7.1.5). \verb+Reason+ is a binary containing any text the
  client sent to indicate the reason for closing the socket; this binary
  may be empty.

\end{itemize}

The \verb+handle_message/1+ callback function supplies one of the
following as a return value:

\begin{itemize}

\item \verb+noreply+ --- do nothing, just wait for the next message.

\item \verb+{reply, {Type, Data}}+ --- reply to the
  message. \verb+Type+ must be either \verb+text+ or \verb+binary+ to
  indicate the type of data in the reply message, and \verb+Data+ is
  the reply message itself.

\item \verb+{close, Reason}+ --- close the connection and exit the
  handling process with \verb+Reason+. For a regular non-error close,
  \verb+Reason+ should be the atom \verb+normal+. \verb+Reason+ may
  alternatively be any allowed numerical value specified for
  \verb+close+ frames in section 7.4 of RFC 6455. Callback handlers
  for \verb+close+ messages from the client must always return
  \verb+{close, Reason}+.

\end{itemize}

To inform \Yaws\ of the details of the callback module, return
\verb+{websocket, CallbackModule, Options}+ from your \verb+out/1+
function, where \verb+CallbackModule+ is the name of your callback
module and \verb+Options+ is a list of options. The following options
are available:

\begin{itemize}

\item \verb+{callback, CallbackType}+ --- supply this atom to indicate
  the type of the callback module. \\ \verb+CallbackType+ can be
  either of the following:

\begin{itemize}

\item \verb+basic+ --- specify this to indicate your callback module
  is the basic type. This is the default.

\item \verb+{advanced, InitialState}+ --- specify this to indicate
  your callback module is an advanced callback module. Here,
  \verb+InitialState+ is the callback's initial state for handling
  this client. See \ref{advanced_ws} for more details.

\end{itemize}

\item \verb+{origin, Origin}+ --- specify the \verb+Origin+ URL from
  which messages will be accepted. This is useful for protecting
  against cross-site attacks. This option defaults to \verb+any+,
  meaning calls will be accepted from any origin.

\end{itemize}

\subsection{Advanced Callback Modules}
\label{advanced_ws}

Advanced callback modules---those that want to supply their own
initial state and are prepared to handle fragmented messages
themselves---supply a \verb+handle_message/2+ callback function.

To indicate an advanced callback module, include
\verb+{callback, {advanced, InitialState}}+ in the \\ \verb+Options+
list when you return \verb+{websocket, CallbackModule, Options}+ from
your \verb+out/1+ function, as described above.

The arguments to the \verb+handle_message/2+ callback
function are as follows:

\begin{itemize}

\item \verb+#ws_frame_info+ --- this record, defined in
  \verb+include/yaws_api.hrl+, provides all details of a frame
  section. See section 5 of RFC 6455 for details.

\item \verb+State+ --- this is the callback module's current
  state. The initial state is supplied when you return
  \verb+{callback, {advanced, InitialState}}+ as part of the options
  list you returned from your \verb+out/1+ function to establish the
  WebSocket callback module.

\end{itemize}

The return values for the \verb+handle_message/2+ callback function
can be any of the following:

\begin{itemize}

\item \verb+{noreply, State}+ --- do nothing, just wait for the next
  message. \verb+State+ is the (possibly updated) state for the
  callback module.

\item \verb+{reply, Reply, State}+ --- reply to the received message
  with \verb+Reply+, which is either \\ \verb+{text, Data}+ or
  \verb+{binary, Data}+. \verb+State+ is the (possibly updated) state
  for the callback module.

\item \verb+{close, Reason}+ --- close the connection and exit the
  handling process with \verb+Reason+. For a regular non-error close,
  \verb+Reason+ should be the atom \verb+normal+. \verb+Reason+ may
  alternatively be any allowed numerical value specified for
  \verb+close+ frames in section 7.4 of RFC 6455. Callback handlers
  for \verb+close+ frames from the client must always return
  \verb+{close, Reason}+.

\end{itemize}

\end{document}
Something went wrong with that request. Please try again.