/usr/share/doc/apcupsd/manual/manual.html is in apcupsd-doc 3.14.14-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 3348 3349 3350 3351 3352 3353 3354 3355 3356 3357 3358 3359 3360 3361 3362 3363 3364 3365 3366 3367 3368 3369 3370 3371 3372 3373 3374 3375 3376 3377 3378 3379 3380 3381 3382 3383 3384 3385 3386 3387 3388 3389 3390 3391 3392 3393 3394 3395 3396 3397 3398 3399 3400 3401 3402 3403 3404 3405 3406 3407 3408 3409 3410 3411 3412 3413 3414 3415 3416 3417 3418 3419 3420 3421 3422 3423 3424 3425 3426 3427 3428 3429 3430 3431 3432 3433 3434 3435 3436 3437 3438 3439 3440 3441 3442 3443 3444 3445 3446 3447 3448 3449 3450 3451 3452 3453 3454 3455 3456 3457 3458 3459 3460 3461 3462 3463 3464 3465 3466 3467 3468 3469 3470 3471 3472 3473 3474 3475 3476 3477 3478 3479 3480 3481 3482 3483 3484 3485 3486 3487 3488 3489 3490 3491 3492 3493 3494 3495 3496 3497 3498 3499 3500 3501 3502 3503 3504 3505 3506 3507 3508 3509 3510 3511 3512 3513 3514 3515 3516 3517 3518 3519 3520 3521 3522 3523 3524 3525 3526 3527 3528 3529 3530 3531 3532 3533 3534 3535 3536 3537 3538 3539 3540 3541 3542 3543 3544 3545 3546 3547 3548 3549 3550 3551 3552 3553 3554 3555 3556 3557 3558 3559 3560 3561 3562 3563 3564 3565 3566 3567 3568 3569 3570 3571 3572 3573 3574 3575 3576 3577 3578 3579 3580 3581 3582 3583 3584 3585 3586 3587 3588 3589 3590 3591 3592 3593 3594 3595 3596 3597 3598 3599 3600 3601 3602 3603 3604 3605 3606 3607 3608 3609 3610 3611 3612 3613 3614 3615 3616 3617 3618 3619 3620 3621 3622 3623 3624 3625 3626 3627 3628 3629 3630 3631 3632 3633 3634 3635 3636 3637 3638 3639 3640 3641 3642 3643 3644 3645 3646 3647 3648 3649 3650 3651 3652 3653 3654 3655 3656 3657 3658 3659 3660 3661 3662 3663 3664 3665 3666 3667 3668 3669 3670 3671 3672 3673 3674 3675 3676 3677 3678 3679 3680 3681 3682 3683 3684 3685 3686 3687 3688 3689 3690 3691 3692 3693 3694 3695 3696 3697 3698 3699 3700 3701 3702 3703 3704 3705 3706 3707 3708 3709 3710 3711 3712 3713 3714 3715 3716 3717 3718 3719 3720 3721 3722 3723 3724 3725 3726 3727 3728 3729 3730 3731 3732 3733 3734 3735 3736 3737 3738 3739 3740 3741 3742 3743 3744 3745 3746 3747 3748 3749 3750 3751 3752 3753 3754 3755 3756 3757 3758 3759 3760 3761 3762 3763 3764 3765 3766 3767 3768 3769 3770 3771 3772 3773 3774 3775 3776 3777 3778 3779 3780 3781 3782 3783 3784 3785 3786 3787 3788 3789 3790 3791 3792 3793 3794 3795 3796 3797 3798 3799 3800 3801 3802 3803 3804 3805 3806 3807 3808 3809 3810 3811 3812 3813 3814 3815 3816 3817 3818 3819 3820 3821 3822 3823 3824 3825 3826 3827 3828 3829 3830 3831 3832 3833 3834 3835 3836 3837 3838 3839 3840 3841 3842 3843 3844 3845 3846 3847 3848 3849 3850 3851 3852 3853 3854 3855 3856 3857 3858 3859 3860 3861 3862 3863 3864 3865 3866 3867 3868 3869 3870 3871 3872 3873 3874 3875 3876 3877 3878 3879 3880 3881 3882 3883 3884 3885 3886 3887 3888 3889 3890 3891 3892 3893 3894 3895 3896 3897 3898 3899 3900 3901 3902 3903 3904 3905 3906 3907 3908 3909 3910 3911 3912 3913 3914 3915 3916 3917 3918 3919 3920 3921 3922 3923 3924 3925 3926 3927 3928 3929 3930 3931 3932 3933 3934 3935 3936 3937 3938 3939 3940 3941 3942 3943 3944 3945 3946 3947 3948 3949 3950 3951 3952 3953 3954 3955 3956 3957 3958 3959 3960 3961 3962 3963 3964 3965 3966 3967 3968 3969 3970 3971 3972 3973 3974 3975 3976 3977 3978 3979 3980 3981 3982 3983 3984 3985 3986 3987 3988 3989 3990 3991 3992 3993 3994 3995 3996 3997 3998 3999 4000 4001 4002 4003 4004 4005 4006 4007 4008 4009 4010 4011 4012 4013 4014 4015 4016 4017 4018 4019 4020 4021 4022 4023 4024 4025 4026 4027 4028 4029 4030 4031 4032 4033 4034 4035 4036 4037 4038 4039 4040 4041 4042 4043 4044 4045 4046 4047 4048 4049 4050 4051 4052 4053 4054 4055 4056 4057 4058 4059 4060 4061 4062 4063 4064 4065 4066 4067 4068 4069 4070 4071 4072 4073 4074 4075 4076 4077 4078 4079 4080 4081 4082 4083 4084 4085 4086 4087 4088 4089 4090 4091 4092 4093 4094 4095 4096 4097 4098 4099 4100 4101 4102 4103 4104 4105 4106 4107 4108 4109 4110 4111 4112 4113 4114 4115 4116 4117 4118 4119 4120 4121 4122 4123 4124 4125 4126 4127 4128 4129 4130 4131 4132 4133 4134 4135 4136 4137 4138 4139 4140 4141 4142 4143 4144 4145 4146 4147 4148 4149 4150 4151 4152 4153 4154 4155 4156 4157 4158 4159 4160 4161 4162 4163 4164 4165 4166 4167 4168 4169 4170 4171 4172 4173 4174 4175 4176 4177 4178 4179 4180 4181 4182 4183 4184 4185 4186 4187 4188 4189 4190 4191 4192 4193 4194 4195 4196 4197 4198 4199 4200 4201 4202 4203 4204 4205 4206 4207 4208 4209 4210 4211 4212 4213 4214 4215 4216 4217 4218 4219 4220 4221 4222 4223 4224 4225 4226 4227 4228 4229 4230 4231 4232 4233 4234 4235 4236 4237 4238 4239 4240 4241 4242 4243 4244 4245 4246 4247 4248 4249 4250 4251 4252 4253 4254 4255 4256 4257 4258 4259 4260 4261 4262 4263 4264 4265 4266 4267 4268 4269 4270 4271 4272 4273 4274 4275 4276 4277 4278 4279 4280 4281 4282 4283 4284 4285 4286 4287 4288 4289 4290 4291 4292 4293 4294 4295 4296 4297 4298 4299 4300 4301 4302 4303 4304 4305 4306 4307 4308 4309 4310 4311 4312 4313 4314 4315 4316 4317 4318 4319 4320 4321 4322 4323 4324 4325 4326 4327 4328 4329 4330 4331 4332 4333 4334 4335 4336 4337 4338 4339 4340 4341 4342 4343 4344 4345 4346 4347 4348 4349 4350 4351 4352 4353 4354 4355 4356 4357 4358 4359 4360 4361 4362 4363 4364 4365 4366 4367 4368 4369 4370 4371 4372 4373 4374 4375 4376 4377 4378 4379 4380 4381 4382 4383 4384 4385 4386 4387 4388 4389 4390 4391 4392 4393 4394 4395 4396 4397 4398 4399 4400 4401 4402 4403 4404 4405 4406 4407 4408 4409 4410 4411 4412 4413 4414 4415 4416 4417 4418 4419 4420 4421 4422 4423 4424 4425 4426 4427 4428 4429 4430 4431 4432 4433 4434 4435 4436 4437 4438 4439 4440 4441 4442 4443 4444 4445 4446 4447 4448 4449 4450 4451 4452 4453 4454 4455 4456 4457 4458 4459 4460 4461 4462 4463 4464 4465 4466 4467 4468 4469 4470 4471 4472 4473 4474 4475 4476 4477 4478 4479 4480 4481 4482 4483 4484 4485 4486 4487 4488 4489 4490 4491 4492 4493 4494 4495 4496 4497 4498 4499 4500 4501 4502 4503 4504 4505 4506 4507 4508 4509 4510 4511 4512 4513 4514 4515 4516 4517 4518 4519 4520 4521 4522 4523 4524 4525 4526 4527 4528 4529 4530 4531 4532 4533 4534 4535 4536 4537 4538 4539 4540 4541 4542 4543 4544 4545 4546 4547 4548 4549 4550 4551 4552 4553 4554 4555 4556 4557 4558 4559 4560 4561 4562 4563 4564 4565 4566 4567 4568 4569 4570 4571 4572 4573 4574 4575 4576 4577 4578 4579 4580 4581 4582 4583 4584 4585 4586 4587 4588 4589 4590 4591 4592 4593 4594 4595 4596 4597 4598 4599 4600 4601 4602 4603 4604 4605 4606 4607 4608 4609 4610 4611 4612 4613 4614 4615 4616 4617 4618 4619 4620 4621 4622 4623 4624 4625 4626 4627 4628 4629 4630 4631 4632 4633 4634 4635 4636 4637 4638 4639 4640 4641 4642 4643 4644 4645 4646 4647 4648 4649 4650 4651 4652 4653 4654 4655 4656 4657 4658 4659 4660 4661 4662 4663 4664 4665 4666 4667 4668 4669 4670 4671 4672 4673 4674 4675 4676 4677 4678 4679 4680 4681 4682 4683 4684 4685 4686 4687 4688 4689 4690 4691 4692 4693 4694 4695 4696 4697 4698 4699 4700 4701 4702 4703 4704 4705 4706 4707 4708 4709 4710 4711 4712 4713 4714 4715 4716 4717 4718 4719 4720 4721 4722 4723 4724 4725 4726 4727 4728 4729 4730 4731 4732 4733 4734 4735 4736 4737 4738 4739 4740 4741 4742 4743 4744 4745 4746 4747 4748 4749 4750 4751 4752 4753 4754 4755 4756 4757 4758 4759 4760 4761 4762 4763 4764 4765 4766 4767 4768 4769 4770 4771 4772 4773 4774 4775 4776 4777 4778 4779 4780 4781 4782 4783 4784 4785 4786 4787 4788 4789 4790 4791 4792 4793 4794 4795 4796 4797 4798 4799 4800 4801 4802 4803 4804 4805 4806 4807 4808 4809 4810 4811 4812 4813 4814 4815 4816 4817 4818 4819 4820 4821 4822 4823 4824 4825 4826 4827 4828 4829 4830 4831 4832 4833 4834 4835 4836 4837 4838 4839 4840 4841 4842 4843 4844 4845 4846 4847 4848 4849 4850 4851 4852 4853 4854 4855 4856 4857 4858 4859 4860 4861 4862 4863 4864 4865 4866 4867 4868 4869 4870 4871 4872 4873 4874 4875 4876 4877 4878 4879 4880 4881 4882 4883 4884 4885 4886 4887 4888 4889 4890 4891 4892 4893 4894 4895 4896 4897 4898 4899 4900 4901 4902 4903 4904 4905 4906 4907 4908 4909 4910 4911 4912 4913 4914 4915 4916 4917 4918 4919 4920 4921 4922 4923 4924 4925 4926 4927 4928 4929 4930 4931 4932 4933 4934 4935 4936 4937 4938 4939 4940 4941 4942 4943 4944 4945 4946 4947 4948 4949 4950 4951 4952 4953 4954 4955 4956 4957 4958 4959 4960 4961 4962 4963 4964 4965 4966 4967 4968 4969 4970 4971 4972 4973 4974 4975 4976 4977 4978 4979 4980 4981 4982 4983 4984 4985 4986 4987 4988 4989 4990 4991 4992 4993 4994 4995 4996 4997 4998 4999 5000 5001 5002 5003 5004 5005 5006 5007 5008 5009 5010 5011 5012 5013 5014 5015 5016 5017 5018 5019 5020 5021 5022 5023 5024 5025 5026 5027 5028 5029 5030 5031 5032 5033 5034 5035 5036 5037 5038 5039 5040 5041 5042 5043 5044 5045 5046 5047 5048 5049 5050 5051 5052 5053 5054 5055 5056 5057 5058 5059 5060 5061 5062 5063 5064 5065 5066 5067 5068 5069 5070 5071 5072 5073 5074 5075 5076 5077 5078 5079 5080 5081 5082 5083 5084 5085 5086 5087 5088 5089 5090 5091 5092 5093 5094 5095 5096 5097 5098 5099 5100 5101 5102 5103 5104 5105 5106 5107 5108 5109 5110 5111 5112 5113 5114 5115 5116 5117 5118 5119 5120 5121 5122 5123 5124 5125 5126 5127 5128 5129 5130 5131 5132 5133 5134 5135 5136 5137 5138 5139 5140 5141 5142 5143 5144 5145 5146 5147 5148 5149 5150 5151 5152 5153 5154 5155 5156 5157 5158 5159 5160 5161 5162 5163 5164 5165 5166 5167 5168 5169 5170 5171 5172 5173 5174 5175 5176 5177 5178 5179 5180 5181 5182 5183 5184 5185 5186 5187 5188 5189 5190 5191 5192 5193 5194 5195 5196 5197 5198 5199 5200 5201 5202 5203 5204 5205 5206 5207 5208 5209 5210 5211 5212 5213 5214 5215 5216 5217 5218 5219 5220 5221 5222 5223 5224 5225 5226 5227 5228 5229 5230 5231 5232 5233 5234 5235 5236 5237 5238 5239 5240 5241 5242 5243 5244 5245 5246 5247 5248 5249 5250 5251 5252 5253 5254 5255 5256 5257 5258 5259 5260 5261 5262 5263 5264 5265 5266 5267 5268 5269 5270 5271 5272 5273 5274 5275 5276 5277 5278 5279 5280 5281 5282 5283 5284 5285 5286 5287 5288 5289 5290 5291 5292 5293 5294 5295 5296 5297 5298 5299 5300 5301 5302 5303 5304 5305 5306 5307 5308 5309 5310 5311 5312 5313 5314 5315 5316 5317 5318 5319 5320 5321 5322 5323 5324 5325 5326 5327 5328 5329 5330 5331 5332 5333 5334 5335 5336 5337 5338 5339 5340 5341 5342 5343 5344 5345 5346 5347 5348 5349 5350 5351 5352 5353 5354 5355 5356 5357 5358 5359 5360 5361 5362 5363 5364 5365 5366 5367 5368 5369 5370 5371 5372 5373 5374 5375 5376 5377 5378 5379 5380 5381 5382 5383 5384 5385 5386 5387 5388 5389 5390 5391 5392 5393 5394 5395 5396 5397 5398 5399 5400 5401 5402 5403 5404 5405 5406 5407 5408 5409 5410 5411 5412 5413 5414 5415 5416 5417 5418 5419 5420 5421 5422 5423 5424 5425 5426 5427 5428 5429 5430 5431 5432 5433 5434 5435 5436 5437 5438 5439 5440 5441 5442 5443 5444 5445 5446 5447 5448 5449 5450 5451 5452 5453 5454 5455 5456 5457 5458 5459 5460 5461 5462 5463 5464 5465 5466 5467 5468 5469 5470 5471 5472 5473 5474 5475 5476 5477 5478 5479 5480 5481 5482 5483 5484 5485 5486 5487 5488 5489 5490 5491 5492 5493 5494 5495 5496 5497 5498 5499 5500 5501 5502 5503 5504 5505 5506 5507 5508 5509 5510 5511 5512 5513 5514 5515 5516 5517 5518 5519 5520 5521 5522 5523 5524 5525 5526 5527 5528 5529 5530 5531 5532 5533 5534 5535 5536 5537 5538 5539 5540 5541 5542 5543 5544 5545 5546 5547 5548 5549 5550 5551 5552 5553 5554 5555 5556 5557 5558 5559 5560 5561 5562 5563 5564 5565 5566 5567 5568 5569 5570 5571 5572 5573 5574 5575 5576 5577 5578 5579 5580 5581 5582 5583 5584 5585 5586 5587 5588 5589 5590 5591 5592 5593 5594 5595 5596 5597 5598 5599 5600 5601 5602 5603 5604 5605 5606 5607 5608 5609 5610 5611 5612 5613 5614 5615 5616 5617 5618 5619 5620 5621 5622 5623 5624 5625 5626 5627 5628 5629 5630 5631 5632 5633 5634 5635 5636 5637 5638 5639 5640 5641 5642 5643 5644 5645 5646 5647 5648 5649 5650 5651 5652 5653 5654 5655 5656 5657 5658 5659 5660 5661 5662 5663 5664 5665 5666 5667 5668 5669 5670 5671 5672 5673 5674 5675 5676 5677 5678 5679 5680 5681 5682 5683 5684 5685 5686 5687 5688 5689 5690 5691 5692 5693 5694 5695 5696 5697 5698 5699 5700 5701 5702 5703 5704 5705 5706 5707 5708 5709 5710 5711 5712 5713 5714 5715 5716 5717 5718 5719 5720 5721 5722 5723 5724 5725 5726 5727 5728 5729 5730 5731 5732 5733 5734 5735 5736 5737 5738 5739 5740 5741 5742 5743 5744 5745 5746 5747 5748 5749 5750 5751 5752 5753 5754 5755 5756 5757 5758 5759 5760 5761 5762 5763 5764 5765 5766 5767 5768 5769 5770 5771 5772 5773 5774 5775 5776 5777 5778 5779 5780 5781 5782 5783 5784 5785 5786 5787 5788 5789 5790 5791 5792 5793 5794 5795 5796 5797 5798 5799 5800 5801 5802 5803 5804 5805 5806 5807 5808 5809 5810 5811 5812 5813 5814 5815 5816 5817 5818 5819 5820 5821 5822 5823 5824 5825 5826 5827 5828 5829 5830 5831 5832 5833 5834 5835 5836 5837 5838 5839 5840 5841 5842 5843 5844 5845 5846 5847 5848 5849 5850 5851 5852 5853 5854 5855 5856 5857 5858 5859 5860 5861 5862 5863 5864 5865 5866 5867 5868 5869 5870 5871 5872 5873 5874 5875 5876 5877 5878 5879 5880 5881 5882 5883 5884 5885 5886 5887 5888 5889 5890 5891 5892 5893 5894 5895 5896 5897 5898 5899 5900 5901 5902 5903 5904 5905 5906 5907 5908 5909 5910 5911 5912 5913 5914 5915 5916 5917 5918 5919 5920 5921 5922 5923 5924 5925 5926 5927 5928 5929 5930 5931 5932 5933 5934 5935 5936 5937 5938 5939 5940 5941 5942 5943 5944 5945 5946 5947 5948 5949 5950 5951 5952 5953 5954 5955 5956 5957 5958 5959 5960 5961 5962 5963 5964 5965 5966 5967 5968 5969 5970 5971 5972 5973 5974 5975 5976 5977 5978 5979 5980 5981 5982 5983 5984 5985 5986 5987 5988 5989 5990 5991 5992 5993 5994 5995 5996 5997 5998 5999 6000 6001 6002 6003 6004 6005 6006 6007 6008 6009 6010 6011 6012 6013 6014 6015 6016 6017 6018 6019 6020 6021 6022 6023 6024 6025 6026 6027 6028 6029 6030 6031 6032 6033 6034 6035 6036 6037 6038 6039 6040 6041 6042 6043 6044 6045 6046 6047 6048 6049 6050 6051 6052 6053 6054 6055 6056 6057 6058 6059 6060 6061 6062 6063 6064 6065 6066 6067 6068 6069 6070 6071 6072 6073 6074 6075 6076 6077 6078 6079 6080 6081 6082 6083 6084 6085 6086 6087 6088 6089 6090 6091 6092 6093 6094 6095 6096 6097 6098 6099 6100 6101 6102 6103 6104 6105 6106 6107 6108 6109 6110 6111 6112 6113 6114 6115 6116 6117 6118 6119 6120 6121 6122 6123 6124 6125 6126 6127 6128 6129 6130 6131 6132 6133 6134 6135 6136 6137 6138 6139 6140 6141 6142 6143 6144 6145 6146 6147 6148 6149 6150 6151 6152 6153 6154 6155 6156 6157 6158 6159 6160 6161 6162 6163 6164 6165 6166 6167 6168 6169 6170 6171 6172 6173 6174 6175 6176 6177 6178 6179 6180 6181 6182 6183 6184 6185 6186 6187 6188 6189 6190 6191 6192 6193 6194 6195 6196 6197 6198 6199 6200 6201 6202 6203 6204 6205 6206 6207 6208 6209 6210 6211 6212 6213 6214 6215 6216 6217 6218 6219 6220 6221 6222 6223 6224 6225 6226 6227 6228 6229 6230 6231 6232 6233 6234 6235 6236 6237 6238 6239 6240 6241 6242 6243 6244 6245 6246 6247 6248 6249 6250 6251 6252 6253 6254 6255 6256 6257 6258 6259 6260 6261 6262 6263 6264 6265 6266 6267 6268 6269 6270 6271 6272 6273 6274 6275 6276 6277 6278 6279 6280 6281 6282 6283 6284 6285 6286 6287 6288 6289 6290 6291 6292 6293 6294 6295 6296 6297 6298 6299 6300 6301 6302 6303 6304 6305 6306 6307 6308 6309 6310 6311 6312 6313 6314 6315 6316 6317 6318 6319 6320 6321 6322 6323 6324 6325 6326 6327 6328 6329 6330 6331 6332 6333 6334 6335 6336 6337 6338 6339 6340 6341 6342 6343 6344 6345 6346 6347 6348 6349 6350 6351 6352 6353 6354 6355 6356 6357 6358 6359 6360 6361 6362 6363 6364 6365 6366 6367 6368 6369 6370 6371 6372 6373 6374 6375 6376 6377 6378 6379 6380 6381 6382 6383 6384 6385 6386 6387 6388 6389 6390 6391 6392 6393 6394 6395 6396 6397 6398 6399 6400 6401 6402 6403 6404 6405 6406 6407 6408 6409 6410 6411 6412 6413 6414 6415 6416 6417 6418 6419 6420 6421 6422 6423 6424 6425 6426 6427 6428 6429 6430 6431 6432 6433 6434 6435 6436 6437 6438 6439 6440 6441 6442 6443 6444 6445 6446 6447 6448 6449 6450 6451 6452 6453 6454 6455 6456 6457 6458 6459 6460 6461 6462 6463 6464 6465 6466 6467 6468 6469 6470 6471 6472 6473 6474 6475 6476 6477 6478 6479 6480 6481 6482 6483 6484 6485 6486 6487 6488 6489 6490 6491 6492 6493 6494 6495 6496 6497 6498 6499 6500 6501 6502 6503 6504 6505 6506 6507 6508 6509 6510 6511 6512 6513 6514 6515 6516 6517 6518 6519 6520 6521 6522 6523 6524 6525 6526 6527 6528 6529 6530 6531 6532 6533 6534 6535 6536 6537 6538 6539 6540 6541 6542 6543 6544 6545 6546 6547 6548 6549 6550 6551 6552 6553 6554 6555 6556 6557 6558 6559 6560 6561 6562 6563 6564 6565 6566 6567 6568 6569 6570 6571 6572 6573 6574 6575 6576 6577 6578 6579 6580 6581 6582 6583 6584 6585 6586 6587 6588 6589 6590 6591 6592 6593 6594 6595 6596 6597 6598 6599 6600 6601 6602 6603 6604 6605 6606 6607 6608 6609 6610 6611 6612 6613 6614 6615 6616 6617 6618 6619 6620 6621 6622 6623 6624 6625 6626 6627 6628 6629 6630 6631 6632 6633 6634 6635 6636 6637 6638 6639 6640 6641 6642 6643 6644 6645 6646 6647 6648 6649 6650 6651 6652 6653 6654 6655 6656 6657 6658 6659 6660 6661 6662 6663 6664 6665 6666 6667 6668 6669 6670 6671 6672 6673 6674 6675 6676 6677 6678 6679 6680 6681 6682 6683 6684 6685 6686 6687 6688 6689 6690 6691 6692 6693 6694 6695 6696 6697 6698 6699 6700 6701 6702 6703 6704 6705 6706 6707 6708 6709 6710 6711 6712 6713 6714 6715 6716 6717 6718 6719 6720 6721 6722 6723 6724 6725 6726 6727 6728 6729 6730 6731 6732 6733 6734 6735 6736 6737 6738 6739 6740 6741 6742 6743 6744 6745 6746 6747 6748 6749 6750 6751 6752 6753 6754 6755 6756 6757 6758 6759 6760 6761 6762 6763 6764 6765 6766 6767 6768 6769 6770 6771 6772 6773 6774 6775 6776 6777 6778 6779 6780 6781 6782 6783 6784 6785 6786 6787 6788 6789 6790 6791 6792 6793 6794 6795 6796 6797 6798 6799 6800 6801 6802 6803 6804 6805 6806 6807 6808 6809 6810 6811 6812 6813 6814 6815 6816 6817 6818 6819 6820 6821 6822 6823 6824 6825 6826 6827 6828 6829 6830 6831 6832 6833 6834 6835 6836 6837 6838 6839 6840 6841 6842 6843 6844 6845 6846 6847 6848 6849 6850 6851 6852 6853 6854 6855 6856 6857 6858 6859 6860 6861 6862 6863 6864 6865 6866 6867 6868 6869 6870 6871 6872 6873 6874 6875 6876 6877 6878 6879 6880 6881 6882 6883 6884 6885 6886 6887 6888 6889 6890 6891 6892 6893 6894 6895 6896 6897 6898 6899 6900 6901 6902 6903 6904 6905 6906 6907 6908 6909 6910 6911 6912 6913 6914 6915 6916 6917 6918 6919 6920 6921 6922 6923 6924 6925 6926 6927 6928 6929 6930 6931 6932 6933 6934 6935 6936 6937 6938 6939 6940 6941 6942 6943 6944 6945 6946 6947 6948 6949 6950 6951 6952 6953 6954 6955 6956 6957 6958 6959 6960 6961 6962 6963 6964 6965 6966 6967 6968 6969 6970 6971 6972 6973 6974 6975 6976 6977 6978 6979 6980 6981 6982 6983 6984 6985 6986 6987 6988 6989 6990 6991 6992 6993 6994 6995 6996 6997 6998 6999 7000 7001 7002 7003 7004 7005 7006 7007 7008 7009 7010 7011 7012 7013 7014 7015 7016 7017 7018 7019 7020 7021 7022 7023 7024 7025 7026 7027 7028 7029 7030 7031 7032 7033 7034 7035 7036 7037 7038 7039 7040 7041 7042 7043 7044 7045 7046 7047 7048 7049 7050 7051 7052 7053 7054 7055 7056 7057 7058 7059 7060 7061 7062 7063 7064 7065 7066 7067 7068 7069 7070 7071 7072 7073 7074 7075 7076 7077 7078 7079 7080 7081 7082 7083 7084 7085 7086 7087 7088 7089 7090 7091 7092 7093 7094 7095 7096 7097 7098 7099 7100 7101 7102 7103 7104 7105 7106 7107 7108 7109 7110 7111 7112 7113 7114 7115 7116 7117 7118 7119 7120 7121 7122 7123 7124 7125 7126 7127 7128 7129 7130 7131 7132 7133 7134 7135 7136 7137 7138 7139 7140 7141 7142 7143 7144 7145 7146 7147 7148 7149 7150 7151 7152 7153 7154 7155 7156 7157 7158 7159 7160 7161 7162 7163 7164 7165 7166 7167 7168 7169 7170 7171 7172 7173 7174 7175 7176 7177 7178 7179 7180 7181 7182 7183 7184 7185 7186 7187 7188 7189 7190 7191 7192 7193 7194 7195 7196 7197 7198 7199 7200 7201 7202 7203 7204 7205 7206 7207 7208 7209 7210 7211 7212 7213 7214 7215 7216 7217 7218 7219 7220 7221 7222 7223 7224 7225 7226 7227 7228 7229 7230 7231 7232 7233 7234 7235 7236 7237 7238 7239 7240 7241 7242 7243 7244 7245 7246 7247 7248 7249 7250 7251 7252 7253 7254 7255 7256 7257 7258 7259 7260 7261 7262 7263 7264 7265 7266 7267 7268 7269 7270 7271 7272 7273 7274 7275 7276 7277 7278 7279 7280 7281 7282 7283 7284 7285 7286 7287 7288 7289 7290 7291 7292 7293 7294 7295 7296 7297 7298 7299 7300 7301 7302 7303 7304 7305 7306 7307 7308 7309 7310 7311 7312 7313 7314 7315 7316 7317 7318 7319 7320 7321 7322 7323 7324 7325 7326 7327 7328 7329 7330 7331 7332 7333 7334 7335 7336 7337 7338 7339 7340 7341 7342 7343 7344 7345 7346 7347 7348 7349 7350 7351 7352 7353 7354 7355 7356 7357 7358 7359 7360 7361 7362 7363 7364 7365 7366 7367 7368 7369 7370 7371 7372 7373 7374 7375 7376 7377 7378 7379 7380 7381 7382 7383 7384 7385 7386 7387 7388 7389 7390 7391 7392 7393 7394 7395 7396 7397 7398 7399 7400 7401 7402 7403 7404 7405 7406 7407 7408 7409 7410 7411 7412 7413 7414 7415 7416 7417 7418 7419 7420 7421 7422 7423 7424 7425 7426 7427 7428 7429 7430 7431 7432 7433 7434 7435 7436 7437 7438 7439 7440 7441 7442 7443 7444 7445 7446 7447 7448 7449 7450 7451 7452 7453 7454 7455 7456 7457 7458 7459 7460 7461 7462 7463 7464 7465 7466 7467 7468 7469 7470 7471 7472 7473 7474 7475 7476 7477 7478 7479 7480 7481 7482 7483 7484 7485 7486 7487 7488 7489 7490 7491 7492 7493 7494 7495 7496 7497 7498 7499 7500 7501 7502 7503 7504 7505 7506 7507 7508 7509 7510 7511 7512 7513 7514 7515 7516 7517 7518 7519 7520 7521 7522 7523 7524 7525 7526 7527 7528 7529 7530 7531 7532 7533 7534 7535 7536 7537 7538 7539 7540 7541 7542 7543 7544 7545 7546 7547 7548 7549 7550 7551 7552 7553 7554 7555 7556 7557 7558 7559 7560 7561 7562 7563 7564 7565 7566 7567 7568 7569 7570 7571 7572 7573 7574 7575 7576 7577 7578 7579 7580 7581 7582 7583 7584 7585 7586 7587 7588 7589 7590 7591 7592 7593 7594 7595 7596 7597 7598 7599 7600 7601 7602 7603 7604 7605 7606 7607 7608 7609 7610 7611 7612 7613 7614 7615 7616 7617 7618 7619 7620 7621 7622 7623 7624 7625 7626 7627 7628 7629 7630 7631 7632 7633 7634 7635 7636 7637 7638 7639 7640 7641 7642 7643 7644 7645 7646 7647 7648 7649 7650 7651 7652 7653 7654 7655 7656 7657 7658 7659 7660 7661 7662 7663 7664 7665 7666 7667 7668 7669 7670 7671 7672 7673 7674 7675 7676 7677 7678 7679 7680 7681 7682 7683 7684 7685 7686 7687 7688 7689 7690 7691 7692 7693 7694 7695 7696 7697 7698 7699 7700 7701 7702 7703 7704 7705 7706 7707 7708 7709 7710 7711 7712 7713 7714 7715 7716 7717 7718 7719 7720 7721 7722 7723 7724 7725 7726 7727 7728 7729 7730 7731 7732 7733 7734 7735 7736 7737 7738 7739 7740 7741 7742 7743 7744 7745 7746 7747 7748 7749 7750 7751 7752 7753 7754 7755 7756 7757 7758 7759 7760 7761 7762 7763 7764 7765 7766 7767 7768 7769 7770 7771 7772 7773 7774 7775 7776 7777 7778 7779 7780 7781 7782 7783 7784 7785 7786 7787 7788 7789 7790 7791 7792 7793 7794 7795 7796 7797 7798 7799 7800 7801 7802 7803 7804 7805 7806 7807 7808 7809 7810 7811 7812 7813 7814 7815 7816 7817 7818 7819 7820 7821 7822 7823 7824 7825 7826 7827 7828 7829 7830 7831 7832 7833 7834 7835 7836 7837 7838 7839 7840 7841 7842 7843 7844 7845 7846 7847 7848 7849 7850 7851 7852 7853 7854 7855 7856 7857 7858 7859 7860 7861 7862 7863 7864 7865 7866 7867 7868 7869 7870 7871 7872 7873 7874 7875 7876 7877 7878 7879 7880 7881 7882 7883 7884 7885 7886 7887 7888 7889 7890 7891 7892 7893 7894 7895 7896 7897 7898 7899 7900 7901 7902 7903 7904 7905 7906 7907 7908 7909 7910 7911 7912 7913 7914 7915 7916 7917 7918 7919 7920 7921 7922 7923 7924 7925 7926 7927 7928 7929 7930 7931 7932 7933 7934 7935 7936 7937 7938 7939 7940 7941 7942 7943 7944 7945 7946 7947 7948 7949 7950 7951 7952 7953 7954 7955 7956 7957 7958 7959 7960 7961 7962 7963 7964 7965 7966 7967 7968 7969 7970 7971 7972 7973 7974 7975 7976 7977 7978 7979 7980 7981 7982 7983 7984 7985 7986 7987 7988 7989 7990 7991 7992 7993 7994 7995 7996 7997 7998 7999 8000 8001 8002 8003 8004 8005 8006 8007 8008 8009 8010 8011 8012 8013 8014 8015 8016 8017 8018 8019 8020 8021 8022 8023 8024 8025 8026 8027 8028 8029 8030 8031 8032 8033 8034 8035 8036 8037 8038 8039 8040 8041 8042 8043 8044 8045 8046 8047 8048 8049 8050 8051 8052 8053 8054 8055 8056 8057 8058 8059 8060 8061 8062 8063 8064 8065 8066 8067 8068 8069 8070 8071 8072 8073 8074 8075 8076 8077 8078 8079 8080 8081 8082 8083 8084 8085 8086 8087 8088 8089 8090 8091 8092 8093 8094 8095 8096 8097 8098 8099 8100 8101 8102 8103 8104 8105 8106 8107 8108 8109 8110 8111 8112 8113 8114 8115 8116 8117 8118 8119 8120 8121 8122 8123 8124 8125 8126 8127 8128 8129 8130 8131 8132 8133 8134 8135 8136 8137 8138 8139 8140 8141 8142 8143 8144 8145 8146 8147 8148 8149 8150 8151 8152 8153 8154 8155 8156 8157 8158 8159 8160 8161 8162 8163 8164 8165 8166 8167 8168 8169 8170 8171 8172 8173 8174 8175 8176 8177 8178 8179 8180 8181 8182 8183 8184 8185 8186 8187 8188 8189 8190 8191 8192 8193 8194 8195 8196 8197 8198 8199 8200 8201 8202 8203 8204 8205 8206 8207 8208 8209 8210 8211 8212 8213 8214 8215 8216 8217 8218 8219 8220 8221 8222 8223 8224 8225 8226 8227 8228 8229 8230 8231 8232 8233 8234 8235 8236 8237 8238 8239 8240 8241 8242 8243 8244 8245 8246 8247 8248 8249 8250 8251 8252 8253 8254 8255 8256 8257 8258 8259 8260 8261 8262 8263 8264 8265 8266 8267 8268 8269 8270 8271 8272 8273 8274 8275 8276 8277 8278 8279 8280 8281 8282 8283 8284 8285 8286 8287 8288 8289 8290 8291 8292 8293 8294 8295 8296 8297 8298 8299 8300 8301 8302 8303 8304 8305 8306 8307 8308 8309 8310 8311 8312 8313 8314 8315 8316 8317 8318 8319 8320 8321 8322 8323 8324 8325 8326 8327 8328 8329 8330 8331 8332 8333 8334 8335 8336 8337 8338 8339 8340 8341 8342 8343 8344 8345 8346 8347 8348 8349 8350 8351 8352 8353 8354 8355 8356 8357 8358 8359 8360 8361 8362 8363 8364 8365 8366 8367 8368 8369 8370 8371 8372 8373 8374 8375 8376 8377 8378 8379 8380 8381 8382 8383 8384 8385 8386 8387 8388 8389 8390 8391 8392 8393 8394 8395 8396 8397 8398 8399 8400 8401 8402 8403 8404 8405 8406 8407 8408 8409 8410 8411 8412 8413 8414 8415 8416 | <?xml version="1.0" encoding="utf-8" ?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<meta name="generator" content="Docutils 0.6: http://docutils.sourceforge.net/" />
<title>APCUPSD User Manual</title>
<style type="text/css">
/*
:Author: David Goodger (goodger@python.org)
:Id: $Id: html4css1.css 5951 2009-05-18 18:03:10Z milde $
:Copyright: This stylesheet has been placed in the public domain.
Default cascading style sheet for the HTML output of Docutils.
See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
customize this style sheet.
*/
/* used to remove borders from tables and images */
.borderless, table.borderless td, table.borderless th {
border: 0 }
table.borderless td, table.borderless th {
/* Override padding for "table.docutils td" with "! important".
The right padding separates the table cells. */
padding: 0 0.5em 0 0 ! important }
.first {
/* Override more specific margin styles with "! important". */
margin-top: 0 ! important }
.last, .with-subtitle {
margin-bottom: 0 ! important }
.hidden {
display: none }
a.toc-backref {
text-decoration: none ;
color: black }
blockquote.epigraph {
margin: 2em 5em ; }
dl.docutils dd {
margin-bottom: 0.5em }
/* Uncomment (and remove this text!) to get bold-faced definition list terms
dl.docutils dt {
font-weight: bold }
*/
div.abstract {
margin: 2em 5em }
div.abstract p.topic-title {
font-weight: bold ;
text-align: center }
div.admonition, div.attention, div.caution, div.danger, div.error,
div.hint, div.important, div.note, div.tip, div.warning {
margin: 2em ;
border: medium outset ;
padding: 1em }
div.admonition p.admonition-title, div.hint p.admonition-title,
div.important p.admonition-title, div.note p.admonition-title,
div.tip p.admonition-title {
font-weight: bold ;
font-family: sans-serif }
div.attention p.admonition-title, div.caution p.admonition-title,
div.danger p.admonition-title, div.error p.admonition-title,
div.warning p.admonition-title {
color: red ;
font-weight: bold ;
font-family: sans-serif }
/* Uncomment (and remove this text!) to get reduced vertical space in
compound paragraphs.
div.compound .compound-first, div.compound .compound-middle {
margin-bottom: 0.5em }
div.compound .compound-last, div.compound .compound-middle {
margin-top: 0.5em }
*/
div.dedication {
margin: 2em 5em ;
text-align: center ;
font-style: italic }
div.dedication p.topic-title {
font-weight: bold ;
font-style: normal }
div.figure {
margin-left: 2em ;
margin-right: 2em }
div.footer, div.header {
clear: both;
font-size: smaller }
div.line-block {
display: block ;
margin-top: 1em ;
margin-bottom: 1em }
div.line-block div.line-block {
margin-top: 0 ;
margin-bottom: 0 ;
margin-left: 1.5em }
div.sidebar {
margin: 0 0 0.5em 1em ;
border: medium outset ;
padding: 1em ;
background-color: #ffffee ;
width: 40% ;
float: right ;
clear: right }
div.sidebar p.rubric {
font-family: sans-serif ;
font-size: medium }
div.system-messages {
margin: 5em }
div.system-messages h1 {
color: red }
div.system-message {
border: medium outset ;
padding: 1em }
div.system-message p.system-message-title {
color: red ;
font-weight: bold }
div.topic {
margin: 2em }
h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
margin-top: 0.4em }
h1.title {
text-align: center }
h2.subtitle {
text-align: center }
hr.docutils {
width: 75% }
img.align-left, .figure.align-left{
clear: left ;
float: left ;
margin-right: 1em }
img.align-right, .figure.align-right {
clear: right ;
float: right ;
margin-left: 1em }
.align-left {
text-align: left }
.align-center {
clear: both ;
text-align: center }
.align-right {
text-align: right }
/* reset inner alignment in figures */
div.align-right {
text-align: left }
/* div.align-center * { */
/* text-align: left } */
ol.simple, ul.simple {
margin-bottom: 1em }
ol.arabic {
list-style: decimal }
ol.loweralpha {
list-style: lower-alpha }
ol.upperalpha {
list-style: upper-alpha }
ol.lowerroman {
list-style: lower-roman }
ol.upperroman {
list-style: upper-roman }
p.attribution {
text-align: right ;
margin-left: 50% }
p.caption {
font-style: italic }
p.credits {
font-style: italic ;
font-size: smaller }
p.label {
white-space: nowrap }
p.rubric {
font-weight: bold ;
font-size: larger ;
color: maroon ;
text-align: center }
p.sidebar-title {
font-family: sans-serif ;
font-weight: bold ;
font-size: larger }
p.sidebar-subtitle {
font-family: sans-serif ;
font-weight: bold }
p.topic-title {
font-weight: bold }
pre.address {
margin-bottom: 0 ;
margin-top: 0 ;
font: inherit }
pre.literal-block, pre.doctest-block {
margin-left: 2em ;
margin-right: 2em }
span.classifier {
font-family: sans-serif ;
font-style: oblique }
span.classifier-delimiter {
font-family: sans-serif ;
font-weight: bold }
span.interpreted {
font-family: sans-serif }
span.option {
white-space: nowrap }
span.pre {
white-space: pre }
span.problematic {
color: red }
span.section-subtitle {
/* font-size relative to parent (h1..h6 element) */
font-size: 80% }
table.citation {
border-left: solid 1px gray;
margin-left: 1px }
table.docinfo {
margin: 2em 4em }
table.docutils {
margin-top: 0.5em ;
margin-bottom: 0.5em }
table.footnote {
border-left: solid 1px black;
margin-left: 1px }
table.docutils td, table.docutils th,
table.docinfo td, table.docinfo th {
padding-left: 0.5em ;
padding-right: 0.5em ;
vertical-align: top }
table.docutils th.field-name, table.docinfo th.docinfo-name {
font-weight: bold ;
text-align: left ;
white-space: nowrap ;
padding-left: 0 }
h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
font-size: 100% }
ul.auto-toc {
list-style-type: none }
</style>
</head>
<body>
<div class="document">
<img alt="./apcupsd.png" src="./apcupsd.png" />
<div class="section" id="apcupsd-user-manual">
<h1>APCUPSD User Manual</h1>
<div class="line-block">
<div class="line"><strong>Adam Kropelin</strong></div>
<div class="line"><strong>Kern Sibbald</strong></div>
</div>
<p><strong>Apcupsd is a UPS control system that permits orderly shutdown of your
computer in the event of a power failure.</strong></p>
<div class="line-block">
<div class="line">February 8, 2015 12:53:50</div>
<div class="line">This manual documents apcupsd version 3.14.x</div>
<div class="line">Copyright © 2004-2015 Adam Kropelin</div>
<div class="line">Copyright © 1999-2005 Kern Sibbald</div>
</div>
<p><em>Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the name Apcupsd,
the copyright notice, and this notice are preserved.</em></p>
<p><em>Apcupsd source code is released under the GNU General Public License
version 2. Please see the file COPYING in the main source directory.</em></p>
<p>For more information on the project, please visit the main web site
at <a class="reference external" href="http://www.apcupsd.com">http://www.apcupsd.com</a></p>
<hr class="docutils" />
<div class="contents local topic" id="table-of-contents">
<p class="topic-title first">Table of Contents</p>
<ul class="simple">
<li><a class="reference internal" href="#important-legal-disclaimer" id="id46">Important Legal Disclaimer</a></li>
<li><a class="reference internal" href="#how-to-use-this-manual" id="id47">How To Use This Manual</a></li>
<li><a class="reference internal" href="#basic-user-s-guide" id="id48">Basic User's Guide</a><ul>
<li><a class="reference internal" href="#quick-start-for-beginners" id="id49">Quick Start for Beginners</a></li>
<li><a class="reference internal" href="#supported-operating-systems" id="id50">Supported Operating Systems</a><ul>
<li><a class="reference internal" href="#platform-support" id="id51">Platform Support</a></li>
</ul>
</li>
<li><a class="reference internal" href="#supported-upses-and-cables" id="id52">Supported UPSes and Cables</a></li>
<li><a class="reference internal" href="#choosing-a-configuration-type" id="id53">Choosing a Configuration Type</a></li>
<li><a class="reference internal" href="#configuration-types" id="id54">Configuration types</a></li>
</ul>
</li>
<li><a class="reference internal" href="#usb-configuration" id="id55">USB Configuration</a><ul>
<li><a class="reference internal" href="#linux-usb-configuration" id="id56">Linux USB Configuration</a><ul>
<li><a class="reference internal" href="#known-linux-usb-issues" id="id57">Known Linux USB Issues</a></li>
<li><a class="reference internal" href="#verifying-device-detection-and-driver" id="id58">Verifying Device Detection and Driver</a></li>
<li><a class="reference internal" href="#device-nodes" id="id59">Device Nodes</a></li>
<li><a class="reference internal" href="#miscellaneous" id="id60">Miscellaneous</a></li>
</ul>
</li>
<li><a class="reference internal" href="#bsd-usb-configuration" id="id61">BSD USB Configuration</a><ul>
<li><a class="reference internal" href="#known-bsd-usb-issues" id="id62">Known BSD USB Issues</a></li>
<li><a class="reference internal" href="#platforms-and-versions" id="id63">Platforms and Versions</a></li>
<li><a class="reference internal" href="#kernel-configuration" id="id64">Kernel Configuration</a></li>
<li><a class="reference internal" href="#id30" id="id65">Verifying Device Detection and Driver</a></li>
<li><a class="reference internal" href="#id31" id="id66">Device Nodes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#windows-usb-configuration" id="id67">Windows USB Configuration</a><ul>
<li><a class="reference internal" href="#id32" id="id68">Platforms and Versions</a></li>
<li><a class="reference internal" href="#usb-driver-installation" id="id69">USB Driver Installation</a></li>
<li><a class="reference internal" href="#id33" id="id70">Verifying Device Detection and Driver</a></li>
</ul>
</li>
<li><a class="reference internal" href="#solaris-usb-configuration" id="id71">Solaris USB Configuration</a><ul>
<li><a class="reference internal" href="#id34" id="id72">Platforms and Versions</a></li>
<li><a class="reference internal" href="#building-apcupsd-with-usb" id="id73">Building Apcupsd with USB</a></li>
<li><a class="reference internal" href="#id35" id="id74">Verifying Device Detection and Driver</a></li>
<li><a class="reference internal" href="#id36" id="id75">Device Nodes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#mac-os-x-darwin-usb-configuration" id="id76">Mac OS X (Darwin) USB Configuration</a><ul>
<li><a class="reference internal" href="#id37" id="id77">Platforms and Versions</a></li>
<li><a class="reference internal" href="#id38" id="id78">Building Apcupsd with USB</a></li>
<li><a class="reference internal" href="#id39" id="id79">Verifying Device Detection and Driver</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#building-and-installing-apcupsd" id="id80">Building and Installing apcupsd</a><ul>
<li><a class="reference internal" href="#installation-from-binary-packages" id="id81">Installation from Binary Packages</a><ul>
<li><a class="reference internal" href="#rpms" id="id82">RPMS</a></li>
<li><a class="reference internal" href="#microsoft-windows" id="id83">Microsoft Windows</a></li>
</ul>
</li>
<li><a class="reference internal" href="#installation-from-source" id="id84">Installation from Source</a></li>
<li><a class="reference internal" href="#verifying-a-source-installation" id="id85">Verifying a Source Installation</a></li>
<li><a class="reference internal" href="#configure-options" id="id86">Configure Options</a></li>
<li><a class="reference internal" href="#recommended-options-for-most-systems" id="id87">Recommended Options for most Systems</a></li>
<li><a class="reference internal" href="#compilers-and-options" id="id88">Compilers and Options</a></li>
<li><a class="reference internal" href="#operating-system-specifics" id="id89">Operating System Specifics</a><ul>
<li><a class="reference internal" href="#debian" id="id90">Debian</a></li>
<li><a class="reference internal" href="#freebsd" id="id91">FreeBSD</a></li>
<li><a class="reference internal" href="#hpux" id="id92">HPUX</a></li>
<li><a class="reference internal" href="#netbsd" id="id93">NetBSD</a></li>
<li><a class="reference internal" href="#mac-os-x-darwin" id="id94">Mac OS X Darwin</a></li>
<li><a class="reference internal" href="#openbsd" id="id95">OpenBSD</a></li>
<li><a class="reference internal" href="#red-hat-systems" id="id96">Red Hat Systems</a></li>
<li><a class="reference internal" href="#slackware" id="id97">Slackware</a></li>
<li><a class="reference internal" href="#suse" id="id98">SUSE</a></li>
<li><a class="reference internal" href="#sun-solaris" id="id99">Sun Solaris</a></li>
<li><a class="reference internal" href="#unknown-system" id="id100">Unknown System</a></li>
<li><a class="reference internal" href="#windows-systems" id="id101">Windows Systems</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#after-installation" id="id102">After Installation</a><ul>
<li><a class="reference internal" href="#checking-your-configuration-file" id="id103">Checking Your Configuration File</a></li>
<li><a class="reference internal" href="#arranging-for-reboot-on-power-up" id="id104">Arranging for Reboot on Power-Up</a></li>
<li><a class="reference internal" href="#making-sure-apcupsd-is-running" id="id105">Making sure apcupsd Is Running</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuration-examples" id="id106">Configuration Examples</a><ul>
<li><a class="reference internal" href="#a-simple-usb-configuration" id="id107">A Simple USB Configuration</a></li>
<li><a class="reference internal" href="#a-simple-configuration-for-a-serial-smartups" id="id108">A Simple Configuration for a Serial SmartUPS</a></li>
<li><a class="reference internal" href="#a-simple-configuration-for-a-simple-signaling-or-dumb" id="id109">A Simple Configuration for a Simple Signaling or Dumb</a></li>
<li><a class="reference internal" href="#nis-server-client-configuration-using-the-net-driver" id="id110">NIS Server/Client Configuration Using the Net Driver</a><ul>
<li><a class="reference internal" href="#differences-between-nis-client-server-and-the-old-now-removed-master-slave-modes" id="id111">Differences between NIS Client/Server and the old (now removed) Master/Slave modes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#powerchute-network-shutdown-driver-pcnet" id="id112">PowerChute Network Shutdown Driver (PCNET)</a></li>
<li><a class="reference internal" href="#modbus-driver" id="id113">MODBUS Driver</a></li>
</ul>
</li>
<li><a class="reference internal" href="#testing-apcupsd" id="id114">Testing Apcupsd</a><ul>
<li><a class="reference internal" href="#process-status-test" id="id115">Process-Status Test</a></li>
<li><a class="reference internal" href="#logging-test" id="id116">Logging Test</a></li>
<li><a class="reference internal" href="#apcaccess-test" id="id117">apcaccess Test</a></li>
<li><a class="reference internal" href="#communications-test" id="id118">Communications Test</a></li>
<li><a class="reference internal" href="#simulated-power-fail-test" id="id119">Simulated Power Fail Test</a></li>
<li><a class="reference internal" href="#system-shutdown-test" id="id120">System Shutdown Test</a></li>
<li><a class="reference internal" href="#full-power-down-test" id="id121">Full Power Down Test</a></li>
<li><a class="reference internal" href="#apctest" id="id122">apctest</a></li>
</ul>
</li>
<li><a class="reference internal" href="#monitoring-and-tuning-your-ups" id="id123">Monitoring and Tuning your UPS</a><ul>
<li><a class="reference internal" href="#apcaccess" id="id124">apcaccess</a></li>
<li><a class="reference internal" href="#apcupsd-notification-and-events" id="id125">Apcupsd Notification and Events</a></li>
<li><a class="reference internal" href="#apcupsd-network-monitoring-cgi-programs" id="id126">apcupsd Network Monitoring (CGI) Programs</a><ul>
<li><a class="reference internal" href="#setting-up-and-testing-the-cgi-programs" id="id127">Setting up and Testing the CGI Programs</a></li>
<li><a class="reference internal" href="#using-the-cgi-programs-on-windows" id="id128">Using the CGI Programs on Windows</a></li>
<li><a class="reference internal" href="#multimon-cgi" id="id129">multimon.cgi</a></li>
<li><a class="reference internal" href="#upsstats-cgi" id="id130">upsstats.cgi</a></li>
<li><a class="reference internal" href="#upsfstatus-cgi" id="id131">upsfstatus.cgi</a></li>
<li><a class="reference internal" href="#a-tip-from-carl-erhorn-for-sun-systems" id="id132">A Tip from Carl Erhorn for Sun Systems:</a></li>
<li><a class="reference internal" href="#cgi-credits" id="id133">CGI Credits</a></li>
</ul>
</li>
<li><a class="reference internal" href="#security-issues" id="id134">Security Issues:</a><ul>
<li><a class="reference internal" href="#firewall-settings" id="id135">Firewall Settings</a></li>
<li><a class="reference internal" href="#tcp-wrappers" id="id136">TCP Wrappers</a></li>
</ul>
</li>
<li><a class="reference internal" href="#configuring-your-eeprom" id="id137">Configuring Your EEPROM</a><ul>
<li><a class="reference internal" href="#using-apctest-to-configure-your-eeprom" id="id138">Using apctest to Configure Your EEPROM</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#maintaining-your-ups-batteries" id="id139">Maintaining Your UPS Batteries</a><ul>
<li><a class="reference internal" href="#battery-technology" id="id140">Battery Technology</a></li>
<li><a class="reference internal" href="#battery-life" id="id141">Battery Life</a></li>
<li><a class="reference internal" href="#flashing-battery-charge-graph-leds" id="id142">Flashing Battery Charge Graph LEDs</a></li>
<li><a class="reference internal" href="#battery-replacement" id="id143">Battery Replacement</a></li>
<li><a class="reference internal" href="#battery-installation" id="id144">Battery Installation</a></li>
<li><a class="reference internal" href="#soft-runtime-calibration" id="id145">"Soft" Runtime Calibration</a></li>
<li><a class="reference internal" href="#manual-runtime-calibration" id="id146">"Manual" Runtime Calibration</a></li>
<li><a class="reference internal" href="#resetting-the-ups-battery-constant" id="id147">Resetting the UPS Battery Constant</a></li>
</ul>
</li>
<li><a class="reference internal" href="#frequently-asked-questions" id="id148">Frequently-Asked Questions</a></li>
<li><a class="reference internal" href="#customizing-event-handling" id="id149">Customizing Event Handling</a><ul>
<li><a class="reference internal" href="#apccontrol-command-line-options" id="id150">apccontrol Command Line Options</a></li>
</ul>
</li>
<li><a class="reference internal" href="#controlling-multiple-upses-on-one-machine" id="id151">Controlling Multiple UPSes on one Machine</a><ul>
<li><a class="reference internal" href="#multiple-ups-example" id="id152">Multiple UPS Example</a></li>
</ul>
</li>
<li><a class="reference internal" href="#support-for-snmp-upses" id="id153">Support for SNMP UPSes</a><ul>
<li><a class="reference internal" href="#planning-and-setup-for-snmp-wiring" id="id154">Planning and Setup for SNMP Wiring</a></li>
<li><a class="reference internal" href="#planning-and-setup-for-snmp-configuration" id="id155">Planning and Setup for SNMP Configuration</a><ul>
<li><a class="reference internal" href="#assign-snmp-card-ip-address" id="id156">Assign SNMP Card IP Address</a></li>
<li><a class="reference internal" href="#set-snmp-card-general-parameters" id="id157">Set SNMP card General Parameters</a></li>
<li><a class="reference internal" href="#set-snmp-card-shutdown-parameters" id="id158">Set SNMP card Shutdown Parameters</a></li>
<li><a class="reference internal" href="#configure-event-trap-receivers" id="id159">Configure Event Trap Receivers</a></li>
</ul>
</li>
<li><a class="reference internal" href="#connecting-apcupsd-to-a-snmp-ups" id="id160">Connecting APCUPSD to a SNMP UPS</a></li>
<li><a class="reference internal" href="#building-with-snmp-support" id="id161">Building with SNMP support</a></li>
<li><a class="reference internal" href="#snmp-trap-catching" id="id162">SNMP Trap Catching</a></li>
<li><a class="reference internal" href="#known-problems" id="id163">Known Problems</a></li>
</ul>
</li>
<li><a class="reference internal" href="#apcupsd-system-logging" id="id164">apcupsd System Logging</a><ul>
<li><a class="reference internal" href="#logging-types" id="id165">Logging Types</a><ul>
<li><a class="reference internal" href="#data-logging" id="id166">Data Logging</a></li>
<li><a class="reference internal" href="#status-logging" id="id167">Status Logging</a></li>
<li><a class="reference internal" href="#events-logging" id="id168">EVENTS Logging</a></li>
</ul>
</li>
<li><a class="reference internal" href="#implementation-details" id="id169">Implementation Details</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-windows-version-of-apcupsd" id="id170">The Windows Version of apcupsd</a><ul>
<li><a class="reference internal" href="#installing-apcupsd-on-windows" id="id171">Installing Apcupsd on Windows</a></li>
<li><a class="reference internal" href="#configuring-apcupsd-on-windows" id="id172">Configuring Apcupsd on Windows</a></li>
<li><a class="reference internal" href="#starting-apcupsd-on-windows" id="id173">Starting Apcupsd on Windows</a></li>
<li><a class="reference internal" href="#apctray" id="id174">Apctray</a></li>
<li><a class="reference internal" href="#testing-apcupsd-on-windows" id="id175">Testing Apcupsd on Windows</a></li>
<li><a class="reference internal" href="#upgrading" id="id176">Upgrading</a></li>
<li><a class="reference internal" href="#post-installation" id="id177">Post-Installation</a></li>
<li><a class="reference internal" href="#problem-areas" id="id178">Problem Areas</a></li>
<li><a class="reference internal" href="#email-notification-of-events" id="id179">Email Notification of Events</a></li>
<li><a class="reference internal" href="#killpower-under-windows" id="id180">Killpower under Windows</a></li>
<li><a class="reference internal" href="#power-down-during-shutdown" id="id181">Power Down During Shutdown</a></li>
<li><a class="reference internal" href="#command-line-options-specific-to-the-windows-version" id="id182">Command Line Options Specific to the Windows Version</a></li>
</ul>
</li>
<li><a class="reference internal" href="#installation-serial-line-upses" id="id183">Installation: Serial-Line UPSes</a><ul>
<li><a class="reference internal" href="#overview-of-serial-interface-upses" id="id184">Overview of Serial-Interface UPSes</a></li>
<li><a class="reference internal" href="#connecting-a-serial-line-ups-to-a-usb-port" id="id185">Connecting a Serial-Line UPS to a USB Port</a></li>
<li><a class="reference internal" href="#testing-serial-line-upses" id="id186">Testing Serial-Line UPSes</a></li>
<li><a class="reference internal" href="#establishing-serial-port-connection" id="id187">Establishing Serial Port Connection</a></li>
<li><a class="reference internal" href="#once-you-have-established-serial-communications" id="id188">Once you have established serial communications</a></li>
<li><a class="reference internal" href="#troubleshooting-serial-line-communications" id="id189">Troubleshooting Serial Line communications</a><ul>
<li><a class="reference internal" href="#bizarre-intermittent-behavior" id="id190">Bizarre Intermittent Behavior:</a></li>
</ul>
</li>
</ul>
</li>
<li><a class="reference internal" href="#cables" id="id191">Cables</a><ul>
<li><a class="reference internal" href="#smart-custom-cable-for-smartupses" id="id192">Smart-Custom Cable for SmartUPSes</a></li>
<li><a class="reference internal" href="#simple-custom-voltage-signalling-cable-for-dumb-upses" id="id193">Simple-Custom Voltage-Signalling Cable for "dumb" UPSes</a></li>
<li><a class="reference internal" href="#custom-rj45-smart-signalling-cable-for-backups-cs-models" id="id194">Custom-RJ45 Smart Signalling Cable for BackUPS CS Models</a></li>
<li><a class="reference internal" href="#other-apc-cables-that-apcupsd-supports" id="id195">Other APC Cables that apcupsd Supports</a></li>
<li><a class="reference internal" href="#voltage-signalling-features-supported-by-apcupsd-for-various-cables" id="id196">Voltage Signalling Features Supported by Apcupsd for Various Cables</a></li>
<li><a class="reference internal" href="#voltage-signalling" id="id197">Voltage Signalling</a></li>
<li><a class="reference internal" href="#the-back-ups-office-500-signals" id="id198">The Back-UPS Office 500 signals</a></li>
<li><a class="reference internal" href="#analyses-of-apc-cables" id="id199">Analyses of APC Cables</a><ul>
<li><a class="reference internal" href="#b-cable-wiring" id="id200">940-0020B Cable Wiring</a></li>
<li><a class="reference internal" href="#c-cable-wiring" id="id201">940-0020C Cable Wiring</a></li>
<li><a class="reference internal" href="#a-cable-wiring" id="id202">940-0023A Cable Wiring</a></li>
<li><a class="reference internal" href="#id40" id="id203">940-0024C Cable Wiring</a></li>
<li><a class="reference internal" href="#id41" id="id204">940-0095A Cable Wiring</a></li>
<li><a class="reference internal" href="#id42" id="id205">940-0095B Cable Wiring</a></li>
<li><a class="reference internal" href="#id43" id="id206">940-0119A Cable Wiring</a></li>
<li><a class="reference internal" href="#serial-backups-es-wiring" id="id207">Serial BackUPS ES Wiring</a></li>
<li><a class="reference internal" href="#id44" id="id208">940-0128A Cable Wiring</a></li>
<li><a class="reference internal" href="#d-cable-wiring" id="id209">940-0128D Cable Wiring</a></li>
<li><a class="reference internal" href="#id45" id="id210">940-0127B Cable Wiring</a></li>
</ul>
</li>
<li><a class="reference internal" href="#win32-implementation-restrictions-for-simple-upses" id="id211">Win32 Implementation Restrictions for Simple UPSes</a></li>
</ul>
</li>
<li><a class="reference internal" href="#recalibrating-the-ups-runtime" id="id212">Recalibrating the UPS Runtime</a></li>
<li><a class="reference internal" href="#configuration-directive-reference" id="id213">Configuration Directive Reference</a><ul>
<li><a class="reference internal" href="#general-configuration-directives" id="id214">General Configuration Directives</a></li>
<li><a class="reference internal" href="#configuration-directives-used-by-the-network-information-server" id="id215">Configuration Directives Used by the Network Information Server</a></li>
<li><a class="reference internal" href="#configuration-directives-used-during-power-failures" id="id216">Configuration Directives used during Power Failures</a></li>
<li><a class="reference internal" href="#configuration-directives-used-to-control-system-logging" id="id217">Configuration Directives used to Control System Logging</a></li>
<li><a class="reference internal" href="#configuration-directives-for-sharing-a-ups" id="id218">Configuration Directives for Sharing a UPS</a></li>
<li><a class="reference internal" href="#configuration-directives-used-to-set-the-ups-eeprom" id="id219">Configuration Directives Used to Set the UPS EEPROM</a></li>
</ul>
</li>
<li><a class="reference internal" href="#apcupsd-status-logging" id="id220">apcupsd Status Logging</a><ul>
<li><a class="reference internal" href="#status-report-format" id="id221">Status report format</a></li>
<li><a class="reference internal" href="#status-report-example" id="id222">Status Report Example</a></li>
<li><a class="reference internal" href="#status-report-fields" id="id223">Status Report Fields</a></li>
<li><a class="reference internal" href="#logging-the-status-information" id="id224">Logging the STATUS Information</a></li>
</ul>
</li>
<li><a class="reference internal" href="#the-shutdown-sequence-and-its-discontents" id="id225">The Shutdown Sequence and its Discontents</a><ul>
<li><a class="reference internal" href="#shutdown-sequence" id="id226">Shutdown Sequence</a></li>
<li><a class="reference internal" href="#shutdown-problems" id="id227">Shutdown Problems</a></li>
<li><a class="reference internal" href="#master-slave-shutdown" id="id228">Master/Slave Shutdown</a></li>
<li><a class="reference internal" href="#startup" id="id229">Startup</a></li>
<li><a class="reference internal" href="#windows-considerations" id="id230">Windows Considerations</a></li>
</ul>
</li>
<li><a class="reference internal" href="#apc-smart-protocol" id="id231">APC smart protocol</a><ul>
<li><a class="reference internal" href="#description" id="id232">Description</a></li>
<li><a class="reference internal" href="#rs-232-differences" id="id233">RS-232 differences</a></li>
<li><a class="reference internal" href="#the-smart-protocol" id="id234">The Smart Protocol</a></li>
<li><a class="reference internal" href="#dip-switch-info" id="id235">Dip switch info</a></li>
<li><a class="reference internal" href="#status-bits" id="id236">Status bits</a></li>
<li><a class="reference internal" href="#alert-messages" id="id237">Alert messages</a></li>
<li><a class="reference internal" href="#register-1" id="id238">Register 1</a></li>
<li><a class="reference internal" href="#register-2" id="id239">Register 2</a></li>
<li><a class="reference internal" href="#register-3" id="id240">Register 3</a></li>
<li><a class="reference internal" href="#interpretation-of-the-old-firmware-revision" id="id241">Interpretation of the Old Firmware Revision</a></li>
<li><a class="reference internal" href="#interpretation-of-the-new-firmware-revision" id="id242">Interpretation of the New Firmware Revision</a></li>
<li><a class="reference internal" href="#eeprom-values" id="id243">EEPROM Values</a></li>
<li><a class="reference internal" href="#programming-the-ups-eeprom" id="id244">Programming the UPS EEPROM</a></li>
</ul>
</li>
<li><a class="reference internal" href="#nis-network-server-protocol" id="id245">NIS Network Server Protocol</a></li>
<li><a class="reference internal" href="#apcupsd-rpm-packaging-faq" id="id246">Apcupsd RPM Packaging FAQ</a></li>
<li><a class="reference internal" href="#credits" id="id247">Credits</a><ul>
<li><a class="reference internal" href="#contributors" id="id248">Contributors</a></li>
<li><a class="reference internal" href="#apcupsd-license" id="id249">Apcupsd License</a></li>
<li><a class="reference internal" href="#other-open-source-licenses" id="id250">Other Open Source Licenses</a></li>
</ul>
</li>
</ul>
</div>
<hr class="docutils" />
<div class="section" id="important-legal-disclaimer">
<h2><a class="toc-backref" href="#id46">Important Legal Disclaimer</a></h2>
<p>No person should rely on the contents of the APCUPSD Manual ("the manual")
without first obtaining advice from APC Technical Support.</p>
<p>The manual is provided on the terms and understanding that:</p>
<blockquote>
<ol class="arabic simple">
<li>the authors, contributors and editors are not responsible for the
results of any actions taken on the basis of information in the manual,
nor for any error in or omission from the manual; and</li>
<li>the authors, contributors and editors are not engaged in rendering
technical or other advice or services.</li>
</ol>
</blockquote>
<p>The the authors, contributors and editors, expressly disclaim all and any
liability and responsibility to any person, whether a reader of the manual
or not, in respect of anything, and of the consequences of anything, done or
omitted to be done by any such person in reliance, whether wholly or partially,
on the whole or any part of the contents of the manual. Without limiting the
generality of the above, no author, contributor or editor shall have any
responsibility for any act or omission of any other author, contributor or
editor.</p>
</div>
<div class="section" id="how-to-use-this-manual">
<h2><a class="toc-backref" href="#id47">How To Use This Manual</a></h2>
<p>This is the manual for apcupsd, a
daemon for communicating with UPSes (Uninterruptible Power
Supplies) made by American Power Conversion Corporation (APC). If you have an
APC-made UPS, whether sold under the APC nameplate or OEMed (for example, the HP
PowerTrust 2997A), and you want you get it working with a computer running
Linux, Unix, or Windows, you are reading the right document.</p>
<p>This manual is divided into parts which increase in technical depth
as they go. If you have just bought a state-of-the-art smart UPS
with a USB or Ethernet interface, and you are running a current
version of Red Hat or SUSE Linux, then apcupsd is
very nearly plug-and-play and you will have to read only the <a class="reference internal" href="#basic-user-s-guide">Basic
User's Guide</a>.</p>
<p>If your operating system is older, or if you have an old-fashioned
serial-line UPS, you'll have to read about serial installation (see
<a class="reference internal" href="#installation-serial-line-upses">Installation: Serial-Line UPSes</a>). If you need more
details about administration for unusual situations (such as a
master/slave or multi-UPS setup) you'll need to read the sections on
those topics as well. Finally,
there are a number of technical reference sections which
gives full details on things like configuration file directives and
event-logging formats.</p>
<p>You should begin by reading the Quick Start (see <a class="reference internal" href="#quick-start-for-beginners">Quick Start for
Beginners</a>) instructions.</p>
</div>
<div class="section" id="basic-user-s-guide">
<h2><a class="toc-backref" href="#id48">Basic User's Guide</a></h2>
<div class="section" id="quick-start-for-beginners">
<h3><a class="toc-backref" href="#id49">Quick Start for Beginners</a></h3>
<p>apcupsd is a complex piece of software, but
most of its complexities are meant for dealing with older hardware
and operating systems. On current hardware and software getting it
running should not be very complicated.</p>
<p>The following is a help guide to the steps needed to get apcupsd
set up and running as painlessly as possible.</p>
<ol class="arabic simple">
<li>Check to see if apcupsd supports your UPS and cable (see
<a class="reference internal" href="#supported-upses-and-cables">Supported UPSes and Cables</a>).</li>
<li>Check to see if apcupsd supports your operating system (see
<a class="reference internal" href="#supported-operating-systems">Supported Operating Systems</a>).</li>
<li>Plan your configuration type (see <a class="reference internal" href="#choosing-a-configuration-type">Choosing a Configuration
Type</a>). If you have just one UPS and
one computer, this is easy. If you have more than one machine being
served by the same UPS, or more than one UPS supplying power to
computers that are on the same local network, you have more choices
to make.</li>
<li>Figure out if you have one of the easy setups. If you have a USB
UPS, and a supported operating system and you want to use one UPS
with one computer, that's an easy setup. APC supplies the cable
needed to talk with that UPS along with the UPS. All you need to do
is check that your USB subsystem is working (see <a class="reference internal" href="#usb-configuration">USB
Configuration</a>); if so, you can go to the build
and install step.</li>
<li>If you have a UPS designed to communicate via SNMP over
Ethernet, that is also a relatively easy installation. Details
are provided in <a class="reference internal" href="#support-for-snmp-upses">Support for SNMP UPSes</a>.</li>
<li>If you have a UPS that communicates via an RS232C serial
interface and it is a SmartUPS, then things are relatively simple,
otherwise, your life is about to get interesting.<ol class="arabic">
<li>If you have a vendor-supplied cable, find out what cable type
you have by looking on the flat ends of the cable for a number,
such as 940-0020A, stamped in the plastic.</li>
<li>If you don't have a vendor-supplied cable, or your type is not
supported, you may have to build one yourself (see
<a class="reference internal" href="#cables">Cables</a>). Here is hoping you are good with a soldering
iron!</li>
</ol>
</li>
<li>Now you are ready to read the Building and Installing (see
<a class="reference internal" href="#building-and-installing-apcupsd">Building and Installing apcupsd</a>)
section of the manual and follow those directions. If you are
installing from an RPM or some other form of binary package, this
step will probably consist of executing a single command.</li>
<li>Tweak your /etc/apcupsd/apcupsd.conf file as necessary. Often it
will not be.</li>
<li>Change the BIOS settings (see <a class="reference internal" href="#arranging-for-reboot-on-power-up">Arranging for Reboot on
Power-Up</a>) on your computer
so that boots up every time it gets power. (This is not the default
on most systems.)</li>
<li>To verify that your UPS is communicating with your computer and
will do the right thing when the power goes out, read and follow
the instructions in the Testing (see <a class="reference internal" href="#testing-apcupsd">Testing
Apcupsd</a>) section.</li>
<li>If you run into problems, check the apcupsd users' email list
archive for similar problems. This is an excellent resource with
answers to all sorts of questions. See
<a class="reference external" href="http://sourceforge.net/mailarchive/forum.php?forum_name=apcupsd-users">http://sourceforge.net/mailarchive/forum.php?forum_name=apcupsd-users</a>.</li>
<li>If you still need help, send a message to the apcupsd users' email
list (<a class="reference external" href="mailto:apcupsd-users@lists.sourceforge.net">apcupsd-users@lists.sourceforge.net</a>) describing your
problem, what version of
apcupsd you are using, what operating system you are using, and
anything else you think might be helpful.</li>
<li>Read the manual section on <a class="reference internal" href="#monitoring-and-tuning-your-ups">Monitoring and Tuning your UPS</a>.</li>
</ol>
</div>
<div class="section" id="supported-operating-systems">
<h3><a class="toc-backref" href="#id50">Supported Operating Systems</a></h3>
<p>apcupsd supports many UNIX-like operating systems as well as several
variants of Windows. Due to lack of API standardization, USB support is not
available on every platform. See <a class="reference internal" href="#platform-support">Platform Support</a> below for details.</p>
<p>In general it is recommended to obtain a prebuilt package for your platform.
Given how apcupsd must integrate into the shutdown mechanism of the
operating system and the rate at which such mechanisms are changed by
vendors, the platform ports in the apcupsd tree may become out of date. In
some cases, binary packages are provided by the apcupsd team (RedHat,
Mandriva, SuSE, Windows, Mac OS X). For other platforms it is recommended to
check your vendor's package repository and third party repositories for
recent binary packages. Note that some vendors continue to distribute
ancient versions of apcupsd with known defects. These packages should <em>not</em> be
used.</p>
<div class="section" id="platform-support">
<h4><a class="toc-backref" href="#id51">Platform Support</a></h4>
<p><strong>LINUX</strong></p>
<ul class="simple">
<li>RedHat <a class="footnote-reference" href="#id26" id="id1">[1]</a> <a class="footnote-reference" href="#id27" id="id2">[2]</a></li>
<li>SuSE <a class="footnote-reference" href="#id27" id="id3">[2]</a></li>
<li>Mandriva/Mandrake <a class="footnote-reference" href="#id27" id="id4">[2]</a></li>
<li>Debian <a class="footnote-reference" href="#id28" id="id5">[3]</a></li>
<li>Slackware <a class="footnote-reference" href="#id28" id="id6">[3]</a></li>
<li>Engarde <a class="footnote-reference" href="#id28" id="id7">[3]</a></li>
<li>Yellowdog <a class="footnote-reference" href="#id28" id="id8">[3]</a></li>
<li>Gentoo <a class="footnote-reference" href="#id28" id="id9">[3]</a></li>
</ul>
<p><strong>WINDOWS</strong></p>
<ul class="simple">
<li>Windows NT 4 <a class="footnote-reference" href="#id27" id="id10">[2]</a> <a class="footnote-reference" href="#id29" id="id11">[4]</a></li>
<li>Windows 98/ME/2000 <a class="footnote-reference" href="#id27" id="id12">[2]</a> <a class="footnote-reference" href="#id29" id="id13">[4]</a></li>
<li>Windows XP/Vista (including 64 bit) <a class="footnote-reference" href="#id26" id="id14">[1]</a> <a class="footnote-reference" href="#id27" id="id15">[2]</a></li>
<li>Windows Server 2003/2008 (including 64 bit) <a class="footnote-reference" href="#id27" id="id16">[2]</a></li>
<li>Windows 7 <a class="footnote-reference" href="#id27" id="id17">[2]</a></li>
</ul>
<p><strong>OTHERS</strong></p>
<ul class="simple">
<li>Mac OS X Darwin <a class="footnote-reference" href="#id26" id="id18">[1]</a> <a class="footnote-reference" href="#id27" id="id19">[2]</a></li>
<li>Solaris 8/9 <a class="footnote-reference" href="#id29" id="id20">[4]</a></li>
<li>Solaris 10</li>
<li>NetBSD</li>
<li>FreeBSD</li>
<li>OpenBSD</li>
<li>HPUX <a class="footnote-reference" href="#id28" id="id21">[3]</a> <a class="footnote-reference" href="#id29" id="id22">[4]</a></li>
<li>Unifix <a class="footnote-reference" href="#id28" id="id23">[3]</a> <a class="footnote-reference" href="#id29" id="id24">[4]</a></li>
<li>QNX <a class="footnote-reference" href="#id29" id="id25">[4]</a></li>
</ul>
<table class="docutils footnote" frame="void" id="id26" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[1]</td><td>Platforms on which apcupsd is regularly developed and tested</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id27" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[2]</td><td>Platforms for which apcupsd team distributes binary packages</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id28" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[3]</td><td>Port included in apcupsd source tree but may be out of date,
unmaintained, or broken.</td></tr>
</tbody>
</table>
<table class="docutils footnote" frame="void" id="id29" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label">[4]</td><td>USB not supported</td></tr>
</tbody>
</table>
</div>
</div>
<div class="section" id="supported-upses-and-cables">
<h3><a class="toc-backref" href="#id52">Supported UPSes and Cables</a></h3>
<p>apcupsd supports nearly every APC brand UPS model in existence and enough
different cable types to connect to all of them.</p>
<p>The <tt class="docutils literal">UPSTYPE <keyword></tt> field is the value you will put in
your /etc/apcupsd/apcupsd.conf file to tell apcupsd what type of UPS
you have. We'll describe the possible values here, because they're
a good way to explain your UPS's single most important interface
property: the kind of protocol it uses to talk with its
computer.</p>
<dl class="docutils">
<dt>apcsmart</dt>
<dd>The 'apcsmart' protocol uses an RS232 serial connection to pass
commands back and forth in a primitive language resembling
modem-control codes. APC calls this language "UPS-Link". Originally
introduced for Smart-UPS models (thus the name 'apcsmart'), this
class of UPS is in decline, rapidly being replaced in APC's product
line by USB and MODBUS UPSes.</dd>
<dt>usb</dt>
<dd>A USB UPS speaks a universal well defined control
language over a USB wire. Most of APC's lineup now uses this method
as of late 2003, and it seems likely to completely take over in
their low- and middle range. The most recent APC UPSes support only a
limited set of data over the USB interface. MODBUS (see below) is required
in order to access the advanced data.</dd>
<dt>net</dt>
<dd>This is the keyword to specify if you are using your
UPS in Slave mode (i.e. the machine is not directly connected to
the UPS, but to another machine which is), and it is connected to
the Master via an ethernet connection. You must have apcupsd's
Network Information Services NIS turned on for this mode to work.</dd>
<dt>snmp</dt>
<dd>SNMP UPSes communicate via an Ethernet NIC and
firmware that speaks Simple Network Management Protocol.</dd>
<dt>dumb</dt>
<dd>A dumb or voltage-signaling UPS and its computer
communicate through the control lines (not the data lines) on an RS232C
serial connection. Not much can actually be conveyed this way other than
an order to shut down. Voltage-signaling UPSes are obsolete; you
are unlikely to encounter one other than as legacy hardware. If you
have a choice, we recommend you avoid simple signalling UPSes.</dd>
<dt>pcnet</dt>
<dd>PCNET is an alternative for SNMP available on APC's
AP9617 family of smart slot modules. The protocol is much simpler
and potentially more secure than SNMP.</dd>
<dt>modbus</dt>
<dd>MODBUS is the newest APC protocol and operates over RS232 serial links or
USB. MODBUS is APC's replacement for the aging 'apcsmart' (aka UPS-Link)
protocol. MODBUS is the only way to access detailed control and status
information on newer (esp. SMT series) UPSes.</dd>
</dl>
</div>
<div class="section" id="choosing-a-configuration-type">
<h3><a class="toc-backref" href="#id53">Choosing a Configuration Type</a></h3>
<p>There are three major
ways of running apcupsd on your system. The first is a standalone
configuration where apcupsd controls a single UPS, which powers a
single computer. This is the most common configuration. If you're
working with just one machine and one UPS, skip the rest of this
section.</p>
<p>Your choices become more interesting if you are running a small
cluster or a big server farm. Under those circumstances, it may not
be possible or even desirable to pair a UPS with every single
machine. apcupsd supports some alternate arrangements.</p>
<p>The second type of configuration is the NIS (Network Information
Server) server and client. In this configuration, where one UPS
powers several computers, a copy of apcupsd running one one
computer will act as a server while the other(s) will act as
network clients which poll the server for information about the
UPS. Note that "NIS" is <em>not</em> related to Sun's directory service
also called "NIS" or "Yellow Pages".</p>
<p>The third configuration is where a single
computer controls multiple UPSes. In this case, there are several
instances of apcupsd on the same computer, each controlling a
different UPS. One instance of apcupsd will run in standalone mode, and
the other instance will normally run in network mode.
This type of configuration may be appropriate for large server
farms that use one dedicated machine for monitoring and
diagnostics</p>
<p>Here is a diagram that summarizes the possibilities:</p>
</div>
<div class="section" id="configuration-types">
<h3><a class="toc-backref" href="#id54">Configuration types</a></h3>
<img alt="./main_configs.png" src="./main_configs.png" />
<p>If you decide to set up one of these more complex configurations,
see the dedicated section on that particular configuration.</p>
</div>
</div>
<div class="section" id="usb-configuration">
<h2><a class="toc-backref" href="#id55">USB Configuration</a></h2>
<p>Apcupsd supports USB connections on all major operating systems:
Linux, FreeBSD, OpenBSD, NetBSD, Windows, Solaris, and Mac OS X
Darwin. If you plan to use a USB connection, please read the
appropriate subsection in its entirety. You can skip this section
if your UPS has a serial (RS232-C) or Ethernet interface or if you
are not running one of the platforms listed above.</p>
<div class="section" id="linux-usb-configuration">
<h3><a class="toc-backref" href="#id56">Linux USB Configuration</a></h3>
<div class="section" id="known-linux-usb-issues">
<h4><a class="toc-backref" href="#id57">Known Linux USB Issues</a></h4>
<dl class="docutils">
<dt><strong>Problem</strong></dt>
<dd>Linux 2.4 series kernels older than 2.4.22 (RH 9, RHEL 3)
do not bind the USB device to the proper driver. This is evidenced
by /proc/bus/usb/devices listing the UPS correctly but it will have
"driver=(none)" instead of "driver=(hid)". This affects RHEL3,
among others.</dd>
<dt><strong>Workaround</strong></dt>
<dd>Upgrade linux kernel to 2.4.22 or higher. Alternately,
you apply the linux-2.4.20-killpower.patch and
linux-2.4.20-USB-reject.patch patches to your kernel and rebuild
it. These patches can be found in the examples/ directory in the
apcupsd source distribution.</dd>
<dt><strong>Problem</strong></dt>
<dd>Mandrake 10.0 and 10.1 systems with high security mode
enabled (running kernel-secure kernel) use static device nodes but
still assign USB minor numbers dynamically. This is evidenced by
<tt class="docutils literal">hiddev0: USB HID v1.10 Device <span class="pre">[...]</span></tt> instead of <tt class="docutils literal">hiddev96: ...</tt> in
dmesg log.</dd>
<dt><strong>Workaround</strong></dt>
<dd>Boot standard kernel instead of kernel-secure or
disable CONFIG_USB_DYNAMIC_MINORS and rebuild kernel-secure.</dd>
<dt><strong>Problem</strong></dt>
<dd>USB driver linux-usb.c fails to compile, reporting errors
about <tt class="docutils literal">HID_MAX_USAGES undefined</tt>. This is due to a defect in the
linux kernel hiddev.h header file on 2.6.5 and higher kernels.</dd>
<dt><strong>Workaround</strong></dt>
<dd>Upgrade to apcupsd-3.10.14 or higher. These versions
contain a workaround for the defect.</dd>
<dt><strong>Problem</strong></dt>
<dd>On some systems such as Slackware 10.0, no USB devices
will show up (see the next section).</dd>
<dt><strong>Workaround</strong></dt>
<dd><p class="first">Add the following to rc.local</p>
<pre class="last literal-block">
mount -t usbdevfs none /proc/bus/usb
</pre>
</dd>
<dt><strong>Problem</strong></dt>
<dd>2.6 kernels use udev and some distributions to not
configure it to automatically create /dev/usb/hiddev?? as they
should, causing apcupsd to fail to locate the UPS.</dd>
<dt><strong>Workaround</strong></dt>
<dd><p class="first">Edit the file /etc/udev/rules.d/50-udev.rules, and add
the following:</p>
<pre class="literal-block">
KERNEL="hiddev*", NAME="usb/hiddev%n"
</pre>
<p class="last">More details are provided in the following section ...</p>
</dd>
</dl>
</div>
<div class="section" id="verifying-device-detection-and-driver">
<h4><a class="toc-backref" href="#id58">Verifying Device Detection and Driver</a></h4>
<p>To make sure that your USB subsystem can see the UPS, just do this
from a shell prompt:</p>
<pre class="literal-block">
cat /proc/bus/usb/devices
</pre>
<p>This information is updated by the kernel whenever a device is
plugged in or unplugged, irrespective of whether apcupsd is running
or not. It contains details on all the USB devices in your system
including hubs (internal and external), input devices, and UPSes.</p>
<p>You should get some output back that includes something like this,
featuring a BackUPS RS 1000:</p>
<pre class="literal-block">
T: Bus=02 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 3 Spd=1.5 MxCh= 0
D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=051d ProdID=0002 Rev= 1.06
S: Manufacturer=American Power Conversion
S: Product=Back-UPS RS 1000 FW:7.g3 .D USB FW:g3
S: SerialNumber=JB0308036505
C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr= 24mA
I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=00 Prot=00 Driver=hid
</pre>
<p>The important things to check for are the <tt class="docutils literal">S:</tt> lines describing
your UPS and and the <tt class="docutils literal">I:</tt> line showing what driver is handling it.
If on the <tt class="docutils literal">I:</tt> line, <tt class="docutils literal">Driver</tt> is listed as <tt class="docutils literal">Driver=none</tt> then
you do not have the HID driver loaded or the driver did not attach
to the UPS. One common cause is having a Linux kernel older than
2.4.22 (such as a stock RedHat 9 or RHEL 3 kernel). If this is the
case for your system, please upgrade to at least kernel version
2.4.22 and try again. If you are already running a 2.4.22 or higher
kernel, please read further for instructions for other possible
courses of action.</p>
<p>Here is another example, this time featuring a Back-UPS 350:</p>
<pre class="literal-block">
T: Bus=01 Lev=01 Prnt=01 Port=00 Cnt=01 Dev#= 2 Spd=1.5 MxCh= 0
D: Ver= 1.10 Cls=00(>ifc ) Sub=00 Prot=00 MxPS= 8 #Cfgs= 1
P: Vendor=051d ProdID=0002 Rev= 1.00
S: Manufacturer=American Power Conversion
S: Product=Back-UPS 350 FW: 5.2.I USB FW: c1
S: SerialNumber=BB0115017954
C:* #Ifs= 1 Cfg#= 1 Atr=a0 MxPwr= 30mA
I: If#= 0 Alt= 0 #EPs= 1 Cls=03(HID ) Sub=00 Prot=00 Driver=hid
E: Ad=81(I) Atr=03(Int.) MxPS= 8 Ivl= 10ms
</pre>
<p>In general, if you see your UPS model in the <tt class="docutils literal">S:</tt> field, which
means <tt class="docutils literal">Manufacturer=</tt>, <tt class="docutils literal">Product=</tt>, and <tt class="docutils literal">SerialNumber=</tt>, and you
see <tt class="docutils literal">Driver=hid</tt> in the <tt class="docutils literal">I:</tt> field, you know the UPS has been
recognized and is bound to the correct driver.</p>
<p>If your UPS doesn't appear in the list at all, check the obvious
things: The UPS must be powered on, and a cable must be properly
seated in both the data port of the UPS and one of your machine's
USB ports. Many UPSes have phone ports to provide surge protection
for phones or modems -- make sure you haven't plugged your USB
cable into one of those rather than the data port (which will
usually be near the top edge of the case.)</p>
<p>Also, ensure that the correct drivers are loaded. Under
Linux-2.4.x, you can check this out easily by examining the
/proc/bus/usb/drivers file. Here's how you can do that:</p>
<pre class="literal-block">
cat /proc/bus/usb/drivers
</pre>
<p>...and you should get:</p>
<pre class="literal-block">
usbdevfs
hub
96-111: hiddev
hid
</pre>
<p>On Linux-2.6.x, make sure the sysfs filesystem is mounted on /sys
and do:</p>
<pre class="literal-block">
ls -l /sys/bus/usb/drivers/
</pre>
<p>...where you should get:</p>
<pre class="literal-block">
total 0
drwxr-xr-x 2 root root 0 May 1 18:55 hid
drwxr-xr-x 2 root root 0 May 1 18:55 hiddev
drwxr-xr-x 2 root root 0 May 1 18:55 hub
drwxr-xr-x 2 root root 0 May 1 18:55 usb
drwxr-xr-x 2 root root 0 May 1 18:55 usbfs
</pre>
<p>...or perhaps something like:</p>
<pre class="literal-block">
total 0
drwxr-xr-x 2 root root 0 Jan 6 15:27 hiddev
drwxr-xr-x 2 root root 0 Jan 6 15:28 hub
drwxr-xr-x 2 root root 0 Jan 6 15:28 usb
drwxr-xr-x 2 root root 0 Jan 6 15:27 usbfs
drwxr-xr-x 2 root root 0 Jan 6 15:28 usbhid
</pre>
<p>If your 2.6.x system does not have the /sys/bus/usb directory,
either you do not have sysfs mounted on /sys or the USB module(s)
have not been loaded. (Check /proc/mounts to make sure sysfs is
mounted.)</p>
<p>A USB UPS needs all of these drivers -- the USB device filesystem,
the USB hub, the Human Interface Device subsystem driver, and the
Human Interface Device driver. If you are compiling your own
kernel, you want to enable</p>
<pre class="literal-block">
CONFIG_USB
CONFIG_USB_HID
CONFIG_USB_HIDDEV
CONFIG_USB_DEVICEFS
</pre>
<p>...as well as at least one USB Host Controller Driver...</p>
<pre class="literal-block">
CONFIG_USB_UHCI_HCD (linux-2.6.x)
CONFIG_USB_OHCI_HCD (linux-2.6.x)
CONFIG_USB_UHCI (linux-2.4.x)
CONFIG_USB_OHCI (linux-2.4.x)
</pre>
</div>
<div class="section" id="device-nodes">
<h4><a class="toc-backref" href="#id59">Device Nodes</a></h4>
<p>Apcupsd accesses USB UPSes via the hiddev device nodes. Typically
these are located in <tt class="docutils literal">/dev/hiddevN</tt>, <tt class="docutils literal">/dev/usb/hiddevN</tt> or
<tt class="docutils literal">/dev/usb/hiddev/hiddevN</tt> (where <tt class="docutils literal">N</tt> is a digit 0 thru 9). Some
distributions (some Debian releases, possibly others) do not
provides these device nodes for you, so you will have to make them
yourself. Check <tt class="docutils literal">/dev</tt>, <tt class="docutils literal">/dev/usb</tt>, and <tt class="docutils literal">/dev/usb/hiddev</tt> and if you
cannot find the <tt class="docutils literal">hiddevN</tt> nodes, run (as root) the
<tt class="docutils literal"><span class="pre">examples/make-hiddev</span></tt> script from the apcupsd source distribution.</p>
<p>Modern Linux distributions using the 2.6 kernel create device nodes
dynamically on the fly as they are needed. It is basically a
hotplug system, giving a lot more power to the user to determine
what happens when a device is probed or opened. It is also a lot
more complicated.</p>
<p>Some early 2.6 distributions (Fedora Core 3, for one) do not
include hiddev rules in their default udev rule set. The bottom
line for apcupsd on such a system is that if the <tt class="docutils literal">hiddevN</tt> is not
created when you plug in your UPS, apcupsd will terminate with an
error. The solution to the problem is to add a rule to the udev
rules file. On Fedora FC3, this file is found in
<tt class="docutils literal"><span class="pre">/etc/udev/rules.d/50-udev.rules</span></tt>. Start by adding the following
line:</p>
<pre class="literal-block">
BUS="usb", SYSFS{idVendor}="051d", NAME="usb/hiddev%n"
</pre>
<p><em>Note that this rule uses obsolete udev syntax and is specific to
FC3 and other distributions of similar vintage.</em></p>
<p>Then either reboot your system, or unplug and replug your UPS and
then restart apcupsd. At that point a <tt class="docutils literal">/dev/usb/hiddevN</tt> node
should appear and apcupsd should work fine.</p>
<p>If you have several UPSes or you just want to give your UPS a fixed
name, you can use rules like the following:</p>
<pre class="literal-block">
KERNEL=="hiddev*", SYSFS{serial}=="JB0319033692", SYMLINK="ups0"
KERNEL=="hiddev*", SYSFS{serial}=="JB0320004845", SYMLINK="ups1"
</pre>
<p><em>Note that this rule uses udev syntax that is appropriate
only for distros such as RHEL4 and FC4 and others of a similar vintage.</em></p>
<p>More recent distros such as FC15 should use something like this:</p>
<pre class="literal-block">
KERNEL=="hiddev*", ATTRS{manufacturer}=="American Power Conversion", ATTRS{serial}=="BB0100009999 ", OWNER="root", SYMLINK+="ups0"
</pre>
<p>Replace the serial number in quotes with the one that corresponds
to your UPS. Then whenever you plug in your UPS a symlink called
ups0, ups1, etc. will be created pointing to the correct hiddev
node. This technique is highly recommended if you have more than
one UPS connected to the same server since rearranging your USB
cables or even upgrading the kernel can affect the order in which
devices are detected and thus change which hiddev node corresponds
to which UPS. If you use the symlink-by-serial-number approach the
link will always point to the correct device node.</p>
<p>You can use...</p>
<pre class="literal-block">
udevinfo -a -p /sys/class/usb/hiddev0/
</pre>
<p>...to get more information on the fields that can be matched
besides serial number.</p>
<p>To find the available attributes to match (note that the serial is NOT always
the UPS serial on the box or in the USB connect message in /var/log/messages),
use:</p>
<pre class="literal-block">
udevadm info --attribute-walk --name=/dev/usb/hiddev0
</pre>
<p>An additional device-node-related problem is the use of dynamic
minors. Some distributions, such as Mandrake 10, ship with a kernel
having <tt class="docutils literal">CONFIG_USB_DYNAMIC_MINORS</tt> turned on. This is not ideal
for running with apcupsd, and the easiest solution is to turn
<tt class="docutils literal">CONFIG_USB_DYNAMIC_MINORS</tt> off and rebuild your kernel, or find a
pre-built kernel with it off. For a kernel with
<tt class="docutils literal">CONFIG_USB_DYNAMIC_MINORS</tt> turned on to work with apcupsd, you
must enable <tt class="docutils literal">devfs</tt>. The following will tell you if devfs is
enabled:</p>
<pre class="literal-block">
$ ps ax | grep devs
</pre>
<p>...which should give something like the following:</p>
<pre class="literal-block">
533 ? S 0:00 devfsd /dev
</pre>
<p>What complicates the situation much more on Mandrake kernels is
their security level since <tt class="docutils literal">CONFIG_DYNAMIC_USB_MINORS</tt> is turned
on, but on higher security levels devfs is turned off. The net
result, is that in those situations hiddev is completely unusable
so apcupsd will not work. So, in these cases, the choices are:</p>
<ol class="arabic simple">
<li>Reduce the security level setting of the system (not sure if
this is possible after the initial install).</li>
<li>Custom build a high security kernel with devfs enabled and make
sure devfs is mounted and devfsd is running.</li>
<li>Custom build a high security kernel with dynamic minors
disabled</li>
<li>Use udev</li>
</ol>
</div>
<div class="section" id="miscellaneous">
<h4><a class="toc-backref" href="#id60">Miscellaneous</a></h4>
<p>If all these things check out and you still can't see the UPS,
something is more seriously wrong than this manual can cover --
find expert help. If you are unable to list USB devices or drivers,
you kernel may not be USB-capable and that needs to be fixed.</p>
</div>
</div>
<div class="section" id="bsd-usb-configuration">
<h3><a class="toc-backref" href="#id61">BSD USB Configuration</a></h3>
<div class="section" id="known-bsd-usb-issues">
<h4><a class="toc-backref" href="#id62">Known BSD USB Issues</a></h4>
<dl class="docutils">
<dt><strong>Problem</strong></dt>
<dd>FreeBSD lockups: Some users have experienced lockups
(apcupsd stops responding) on FreeBSD systems.</dd>
<dt><strong>Solution</strong></dt>
<dd>Recent versions of Apcupsd have addressed this issue.
Please upgrade to apcupsd-3.10.18 or higher.</dd>
<dt><strong>Problem</strong></dt>
<dd>FreeBSD kernel panics if USB cable is unplugged while
apcupsd is running.</dd>
<dt><strong>Solution</strong></dt>
<dd>This is a kernel bug and is most easily worked around by
not hot- unplugging the UPS while apcupsd is running. This issue
may be fixed in recent FreeBSD kernels.</dd>
</dl>
</div>
<div class="section" id="platforms-and-versions">
<h4><a class="toc-backref" href="#id63">Platforms and Versions</a></h4>
<p>The *BSD USB driver supports FreeBSD, OpenBSD and NetBSD. (Thanks
go to the *BSD developers who kept a nearly identical interface
across all three platforms.)</p>
</div>
<div class="section" id="kernel-configuration">
<h4><a class="toc-backref" href="#id64">Kernel Configuration</a></h4>
<p>Users of OpenBSD, NetBSD, and some versions of FreeBSD will need to
rebuild the kernel in order to <em>enable the ugen driver</em> and
<em>disable the uhid driver</em>. uhid is not sufficient for apcupsd at
this time and we need to prevent it from grabbing the UPS device.
You should <em>make the following changes</em> to your kernel config
file:</p>
<dl class="docutils">
<dt><em>FreeBSD (v5.4 and below, v6.0)</em></dt>
<dd><div class="first last line-block">
<div class="line">(you <strong>will not</strong> lose use of USB keyboard and mouse)</div>
<div class="line"><strong>Disable:</strong> uhid</div>
<div class="line"><strong>Enable:</strong> ugen</div>
</div>
</dd>
<dt><em>FreeBSD (v5.5, v6.1 and above)</em></dt>
<dd><div class="first line-block">
<div class="line">(you <strong>will not</strong> lose use of USB keyboard and mouse)</div>
<div class="line"><strong>Disable:</strong> (nothing)</div>
<div class="line"><strong>Enable:</strong> ugen</div>
</div>
<p class="last">This is the default configuration for a GENERIC kernel on many
platforms so you most likely will not need to recompile.</p>
</dd>
<dt><em>NetBSD (v3.x and below)</em></dt>
<dd><div class="first last line-block">
<div class="line">(you <strong>will</strong> lose use of USB keyboard and mouse)</div>
<div class="line"><strong>Disable:</strong> uhidev, ums, wsmouse, ukbd, wskbd, uhid</div>
<div class="line"><strong>Enable:</strong> ugen</div>
</div>
</dd>
<dt><em>NetBSD (v4.0 and above)</em></dt>
<dd><p class="first">You can use apcupsd on single USB port
without disabling the USB keyboard and mouse on other ports, though
all other devices will be disabled on the port you pick for your
UPS.</p>
<p>First, decide which hub and port you wish to use. You can find out
the hub and port numbers for any particular physical connector by
plugging a USB device into it and looking at the messages printed
by the kernel; you should messages something like this:</p>
<pre class="literal-block">
uxx0 at uhub0 port 1
uxx0: <some device name>
</pre>
<p>To use your APC UPS on this port, configure the kernel to prefer
attachment of the ugen driver over other drivers on this hub and
port only, by adding a line like this to your kernel config file:</p>
<pre class="literal-block">
ugen* at uhub0 port 1 flags 1
</pre>
<p>(The "flags 1" forces the ugen to attach instead of anything else
detected there.)</p>
<p>Configure and build that kernel as per the references below, and
your UPS will now attach as a ugen device when plugged into that
port.</p>
<p class="last">Don't forget to '<tt class="docutils literal">cd /dev</tt>' and '<tt class="docutils literal">./MAKEDEV ugen1</tt>' (and 2 and so on)
if you have more than one generic usb device on your system.</p>
</dd>
<dt><em>OpenBSD</em></dt>
<dd><div class="first last line-block">
<div class="line">(you <strong>will</strong> lose use of USB keyboard and mouse):</div>
<div class="line"><strong>Disable:</strong> uhidev, ums, wsmouse, ukbd, wskbd, uhid</div>
<div class="line"><strong>Enable:</strong> ugen</div>
</div>
</dd>
</dl>
<p>For detailed information on rebuilding your kernel, consult these
references:</p>
<dl class="docutils">
<dt><em>FreeBSD</em></dt>
<dd><a class="reference external" href="http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig.html">http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/kernelconfig.html</a></dd>
<dt><em>NetBSD</em></dt>
<dd><a class="reference external" href="http://www.netbsd.org/guide/en/chap-kernel.html">http://www.netbsd.org/guide/en/chap-kernel.html</a></dd>
<dt><em>OpenBSD</em></dt>
<dd><a class="reference external" href="http://www.openbsd.org/faq/faq5.html#Building">http://www.openbsd.org/faq/faq5.html#Building</a></dd>
</dl>
</div>
<div class="section" id="id30">
<h4><a class="toc-backref" href="#id65">Verifying Device Detection and Driver</a></h4>
<p>After building a properly configured kernel, reboot into that
kernel and plug in your UPS USB cable. You should see a dmesg log
message like the following:</p>
<pre class="literal-block">
ugen0: American Power Conversion Back-UPS RS 1500 FW:8.g6 .D USB FW:g6, rev 1.10/1.06, addr 2
</pre>
<p>Note that the <tt class="docutils literal">ugen</tt> driver is called out. If you see <tt class="docutils literal">uhid</tt>
instead, it probably means you did not properly disable the uhid
driver when you compiled your kernel or perhaps you're not running
the new kernel.</p>
<p>You can also check with '<tt class="docutils literal">usbdevs <span class="pre">-d</span></tt>' to get a list of USB devices
recognized by the system as well as the drivers they are associated
with. For example:</p>
<pre class="literal-block">
# usbdevs -d
addr 1: UHCI root hub, VIA
uhub0
addr 2: Back-UPS RS 1500 FW:8.g6 .D USB FW:g6, American Power Conversion
ugen0
</pre>
</div>
<div class="section" id="id31">
<h4><a class="toc-backref" href="#id66">Device Nodes</a></h4>
<p>Apcupsd communicates with the UPS through the USB generic device,
<tt class="docutils literal">ugen</tt>. You may or may not need to manually make <tt class="docutils literal">ugen</tt> device
nodes in <tt class="docutils literal">/dev</tt>, depending on what OS you are using.</p>
<dl class="docutils">
<dt>FreeBSD</dt>
<dd>No manual intervention needed. FreeBSD automatically
creates the ugen nodes on demand.</dd>
<dt>NetBSD</dt>
<dd>By default, NetBSD only creates nodes for the first ugen
device, <tt class="docutils literal">ugen0</tt>. Check <tt class="docutils literal">usbdevs <span class="pre">-d</span></tt> to see which device your
UPS was bound to and then create the appropriate node by running
'<tt class="docutils literal">cd /dev ; ./MAKEDEV ugenN</tt>', where <tt class="docutils literal">ugenN</tt> is the ugen device name
shown by <tt class="docutils literal">usbdevs</tt>. It is probably a good idea to create several sets
of ugen nodes in case you add more USB devices.</dd>
<dt>OpenBSD</dt>
<dd>Similar to NetBSD, OpenBSD creates nodes for <tt class="docutils literal">ugen0</tt> and
<tt class="docutils literal">ugen1</tt>. Check <tt class="docutils literal">usbdevs <span class="pre">-d</span></tt> to see which device your UPS was
bound to and then create the appropriate node by running '<tt class="docutils literal">cd /dev
; ./MAKEDEV ugenN</tt>', where <tt class="docutils literal">ugenN</tt> is the ugen device name shown
by <tt class="docutils literal">usbdevs</tt>. It is probably a good idea to create several sets of
ugen nodes in case you add more USB devices.</dd>
</dl>
</div>
</div>
<div class="section" id="windows-usb-configuration">
<h3><a class="toc-backref" href="#id67">Windows USB Configuration</a></h3>
<div class="section" id="id32">
<h4><a class="toc-backref" href="#id68">Platforms and Versions</a></h4>
<p>Apcupsd supports USB UPSes on Windows XP and newer, including 64 bit systems.</p>
</div>
<div class="section" id="usb-driver-installation">
<h4><a class="toc-backref" href="#id69">USB Driver Installation</a></h4>
<p>USB connected UPSes on Windows require a special driver. In most
cases, this driver is automatically installed when you install
Apcupsd. However in some cases you may need to install the driver manually.
For detailed instructions, please see the <tt class="docutils literal">install.txt</tt> file located
in the driver folder of your Apcupsd install.</p>
</div>
<div class="section" id="id33">
<h4><a class="toc-backref" href="#id70">Verifying Device Detection and Driver</a></h4>
<p>After installing Apcupsd (and the Apcupsd USB driver, if
necessary), plug in your UPS USB cable and open the Windows Device
Manager. You should see a <tt class="docutils literal">American Power Conversion USB UPS (Apcupsd)</tt>
listed under the <tt class="docutils literal">Batteries</tt> section. If a device of that name does not
appear, check that your UPS is powered on and that the USB cable is connected
at both ends. Reinstall the driver as directed above if needed.</p>
</div>
</div>
<div class="section" id="solaris-usb-configuration">
<h3><a class="toc-backref" href="#id71">Solaris USB Configuration</a></h3>
<div class="section" id="id34">
<h4><a class="toc-backref" href="#id72">Platforms and Versions</a></h4>
<p>Apcupsd supports USB UPSes on Solaris 10 and higher. Both x86 and
SPARC platforms are supported.</p>
</div>
<div class="section" id="building-apcupsd-with-usb">
<h4><a class="toc-backref" href="#id73">Building Apcupsd with USB</a></h4>
<p>Some specific packages are necessary when building Apcupsd with USB
support on Solaris. You must install the <tt class="docutils literal">SUNWlibusb</tt> and
<tt class="docutils literal">SUNWlibusbugen</tt> packages <strong>BEFORE</strong> attempting to build Apcupsd.
These packages can be found on the Solaris installation CDROMs and
should be installed with the <tt class="docutils literal">pkgadd</tt> utility.</p>
<p>You also should build using the gcc compiler and ccs make, not
Sun's compiler. The appropriate make utility can be found in
<tt class="docutils literal">/usr/ccs/bin</tt>. gcc can be installed from packages included on the
Solaris installation CDROMs.</p>
<p>Configure and build Apcupsd normally, as described in <a class="reference internal" href="#building-and-installing-apcupsd">Building and
Installing Apcupsd</a>. Be sure to
include the <tt class="docutils literal"><span class="pre">--enable-usb</span></tt> flag to <tt class="docutils literal">configure</tt>.</p>
<p>After building, install Apcupsd as root using '<tt class="docutils literal">make install</tt>',
then <em>perform a reconfigure boot</em> ('<tt class="docutils literal">reboot <span class="pre">--</span> <span class="pre">-r</span></tt>'). During
installation, Apcupsd will automatically configure your USB
subsystem to attach APC USB devices to the <tt class="docutils literal">ugen</tt> driver. This is
a critical step and must be completed by a reconfigure boot. Note
that the USB config changes will be reversed if you remove Apcupsd
using '<tt class="docutils literal">make uninstall</tt>'.</p>
</div>
<div class="section" id="id35">
<h4><a class="toc-backref" href="#id74">Verifying Device Detection and Driver</a></h4>
<p>After installing Apcupsd as described above and performing a
reconfigure boot, plug in your UPS USB cable. You should see a
series of dmesg log messages similar to the following:</p>
<pre class="literal-block">
Dec 5 17:50:50 sunblade usba: [ID 912658 kern.info] USB 1.10 device (usb51d,2) operating at low speed (USB 1.x) on USB 1.10 root hub: input@4, ugen0 at bus address 3
Dec 5 17:50:50 sunblade usba: [ID 349649 kern.info] American Power Conversion Smart-UPS 1000 FW:600.1.D USB FW:1.2 AS0127232356
Dec 5 17:50:50 sunblade genunix: [ID 936769 kern.info] ugen0 is /pci@1f,0/usb@c,3/input@4
Dec 5 17:50:50 sunblade genunix: [ID 408114 kern.info] /pci@1f,0/usb@c,3/input@4 (ugen0) online
</pre>
<p>Note that the <tt class="docutils literal">ugen</tt> driver is called out. If you do not see any
dmesg entries related to your UPS, ensure that it is turned on and
that the USB cable is connected at both ends. Also verify that you
installed Apcupsd as root using the '<tt class="docutils literal">make install</tt>' command and
that you performed a reconfigure boot afterward.</p>
</div>
<div class="section" id="id36">
<h4><a class="toc-backref" href="#id75">Device Nodes</a></h4>
<p>Apcupsd communicates with the UPS through the USB generic device, <tt class="docutils literal">ugen</tt>.
The reconfigure boot performed after Apcupsd installation
will ensure the correct device nodes are created. Once your UPS has
been recognized in dmesg as shown above, you can check /dev/usb to
see if the device nodes have appeared:</p>
<pre class="literal-block">
[user@sunblade /]$ ls /dev/usb/51d.2/*
cntrl0 cntrl0stat devstat if0in1 if0in1stat
</pre>
<p>(<tt class="docutils literal">51d.2</tt> is the vendor/product id for APC UPSes.)</p>
</div>
</div>
<div class="section" id="mac-os-x-darwin-usb-configuration">
<h3><a class="toc-backref" href="#id76">Mac OS X (Darwin) USB Configuration</a></h3>
<div class="section" id="id37">
<h4><a class="toc-backref" href="#id77">Platforms and Versions</a></h4>
<p>Apcupsd supports USB UPSes on Mac OS X (Darwin) 10.4.x and higher.
Both Intel and PowerPC platforms are supported.</p>
</div>
<div class="section" id="id38">
<h4><a class="toc-backref" href="#id78">Building Apcupsd with USB</a></h4>
<p>Some specific packages are necessary when building Apcupsd with USB
support on Darwin. You must install libusb-0.1.12 which
can be obtained from MacPorts (<a class="reference external" href="http://www.macports.org">http://www.macports.org</a>) (formerly
DarwinPorts) or Fink (<a class="reference external" href="http://fink.sourceforge.net">http://fink.sourceforge.net</a>) or downloaded and built
by hand (<a class="reference external" href="http://www.libusb.org">http://www.libusb.org</a>). <em>You must not use
libusb-1.x or higher (apcupsd does not support the new 1.0 APIs) nor
any version earlier than 0.1.12 (earlier versions have a bug that apcupsd
triggers). Generally that means you must use exactly 0.1.12.</em> Note that
Apcupsd is sensitive to the install location of libusb, so beware if you
change it from the default.</p>
<p>Apcupsd should be built using gcc, preferably from the XCode
development tools. Currently the maintainer is using gcc-4.0.1 from
XCode 2.4. Other versions of gcc from other sources may also work.</p>
<p>Configure and build Apcupsd normally, as described in <a class="reference internal" href="#building-and-installing-apcupsd">Building and
Installing Apcupsd</a>. Be sure to
include the <tt class="docutils literal"><span class="pre">--enable-usb</span></tt> flag to <tt class="docutils literal">configure</tt>.</p>
<p>After building, install Apcupsd as root using '<tt class="docutils literal">make install</tt>'
and then reboot. During installation, Apcupsd will automatically
install a simple dummy kext driver designed to prevent Apple's
monitoring software from taking over the UPS. It is necessary to
reboot in order to activate the kext. Note that this kext will be
automatically removed if you uninstall Apcupsd using
'<tt class="docutils literal">make uninstall</tt>', allowing Apple's monitoring tool to once
again access the UPS.</p>
</div>
<div class="section" id="id39">
<h4><a class="toc-backref" href="#id79">Verifying Device Detection and Driver</a></h4>
<p>After installing Apcupsd as described above and rebooting, plug in
your UPS USB cable. You should notice that Darwin does <strong>NOT</strong>
display the battery monitor tool in the menu bar. You can also
check Apple Menu -> About This Mac -> More Info... -> USB to ensure
that your UPS appears in the list of USB devices.</p>
</div>
</div>
</div>
<div class="section" id="building-and-installing-apcupsd">
<h2><a class="toc-backref" href="#id80">Building and Installing apcupsd</a></h2>
<p>In general it is recommended to obtain a prebuilt binary package for your
platform. Given how apcupsd must integrate into the shutdown mechanism of the
operating system and the rate at which such mechanisms are changed by
vendors, the platform ports in the apcupsd tree may become out of date. In
some cases, binary packages are provided by the apcupsd team (RedHat,
Mandriva, SuSE, Windows, Mac OS X). For other platforms it is recommended to
check your vendor's package repository and third party repositories for
recent binary packages before resorting to building apcupsd from scratch.
Note that some vendors continue to distribute <em>ancient</em> versions of apcupsd
with known defects. These packages should <strong>not</strong> be used.</p>
<div class="section" id="installation-from-binary-packages">
<h3><a class="toc-backref" href="#id81">Installation from Binary Packages</a></h3>
<div class="section" id="rpms">
<h4><a class="toc-backref" href="#id82">RPMS</a></h4>
<p>For systems based on RPM packages, such as Red Hat and SuSE, apcupsd is
available in binary RPM format. This is the simplest way to
install. If you have no previous version of apcupsd on your machine
and are creating a standalone configuration, simply install the RPM
with a normal '<tt class="docutils literal">rpm <span class="pre">-ihv</span></tt>' command. You're done, and can now skip
the rest of this chapter and go straight to tweaking your run-time
configuration file. (see <a class="reference internal" href="#after-installation">After Installation</a>)</p>
<p>If you have a previous installation, you can upgrade with a normal
'<tt class="docutils literal">rpm <span class="pre">-Uhv</span></tt>', but this may not upgrade the halt script. It may be
better to do the upgrade as a remove '<tt class="docutils literal">rpm <span class="pre">-e</span></tt>' followed by a
fresh install '<tt class="docutils literal">rpm <span class="pre">-ihv</span></tt>'.</p>
<p>After installation of the binary RPM, please verify carefully that
/etc/rc.d/init.d/halt was properly updated and contains new script
lines flagged with <tt class="docutils literal"><span class="pre">***APCUPSD***</span></tt>.</p>
<p>Since there is no standard location for cgi-bin, the rpm will place
the binary CGI programs in the directory /etc/apcupsd/cgi. To
actually use them, you must copy or move them to your actual
cgi-bin directory, which on many systems is located in
/home/httpd/cgi-bin.</p>
</div>
<div class="section" id="microsoft-windows">
<h4><a class="toc-backref" href="#id83">Microsoft Windows</a></h4>
<p>The Windows version of apcupsd is distributed as a simple double-click
installer. Installation is very simple and straight-forward: Simply
double-click the installer executable and follow the instructions. See
<a class="reference internal" href="#the-windows-version-of-apcupsd">The Windows Version of apcupsd</a> for further details.</p>
</div>
</div>
<div class="section" id="installation-from-source">
<h3><a class="toc-backref" href="#id84">Installation from Source</a></h3>
<p>Installation from source might have to be be done different ways
depending on what system you are running. The basic procedure
involves getting a source distribution, running the configuration,
rebuilding, and installing.</p>
<p>For building the system, we suggest that you run the configure and
make processes as your normal UNIX user ID. The '<tt class="docutils literal">make install</tt>'
must be run as root. But if your normal ID has an environment setup
for using the C compiler, it's simpler to do that than to set up
root to have the correct environment.</p>
<p>apcupsd requires <tt class="docutils literal">gcc</tt> and <tt class="docutils literal">g++</tt> compilers as well as GNU <tt class="docutils literal">make</tt>.
Other compilers or BSD <tt class="docutils literal">make</tt> will <strong>not</strong> work. GNU make is sometimes
installed as <tt class="docutils literal">gmake</tt>. The configure script will check for this and will
inform you of what command to use to invoke GNU make.</p>
<p>The basic installation from a tar source file is rather simple:</p>
<ol class="arabic simple">
<li>Unpack the source code from its tar archive.</li>
<li>Go into the directory containing the source code.</li>
<li>Run '<tt class="docutils literal">./configure</tt>' (with appropriate options as described
below)</li>
<li>'<tt class="docutils literal">make</tt>' or '<tt class="docutils literal">gmake</tt>'' as instructed by configure</li>
<li>'<tt class="docutils literal">su</tt>' (i.e. become root)</li>
<li>Stop any running instance of apcupsd. The command to do this
will look like '<tt class="docutils literal"><span class="pre">system-dependent-path/apcupsd</span> stop</tt>'</li>
<li>uninstall any old apcupsd This is important since the default
install locations may have changed.</li>
<li>'<tt class="docutils literal">make install</tt>' or '<tt class="docutils literal">gmake install</tt>'</li>
<li>edit your /etc/apcupsd/apcupsd.conf file if necessary</li>
<li>ensure that your halt script is properly updated</li>
<li>Start the new apcupsd with: '<tt class="docutils literal"><span class="pre">system-dependent-path/apcupsd</span>
start</tt>'</li>
</ol>
<p>If all goes well, the '<tt class="docutils literal">./configure</tt>' will correctly determine which
operating system you are running and configure the source code
appropriately. <tt class="docutils literal">configure</tt> currently recognizes the systems listed
below in the <a class="reference internal" href="#operating-system-specifics">Operating System Specifics</a> section of this chapter and
adapts the configuration appropriately. Check that the
configuration report printed at the end of the <tt class="docutils literal">configure</tt> process
corresponds to your choice of directories, options, and that it has
correctly detected your operating system. If not, redo the
<tt class="docutils literal">configure</tt> with the appropriate options until your configuration is
correct.</p>
<p>Please note that a number of the <tt class="docutils literal">configure</tt> options preset
apcupsd.conf directive values in an attempt to automatically adapt
apcupsd as best possible to your system. You can change the values
in apcupsd.conf at a later time without redoing the configuration
process by simply editing the apcupsd.conf file.</p>
<p>Other configuration options can be used to set up the installation
of HTML documentation and optional modules, notably the CGI
interface that enables the UPS state to be queried via the Web. You
will find a complete reference later in this chapter.</p>
<p>In general, you will probably want to supply a more elaborate
<tt class="docutils literal">configure</tt> statement to ensure that the modules you want are built
and that everything is placed into the correct directories.</p>
<p>On Red Hat, a fairly typical configuration command would look like
the following:</p>
<pre class="literal-block">
CFLAGS="-g -O2" LDFLAGS="-g" ./configure \
--enable-usb \
--with-upstype=usb \
--with-upscable=usb \
--prefix=/usr \
--sbindir=/sbin \
--with-cgi-bin=/var/www/cgi-bin \
--enable-cgi \
--with-log-dir=/etc/apcupsd
</pre>
<p>By default, '<tt class="docutils literal">make install</tt>' will install the executable files in
/sbin, the manuals in /usr/man, and the configuration and script
files in /etc/apcupsd. In addition, if your system is recognized,
certain files such as the startup script and the system halt script
will be placed in appropriate system directories (usually
subdirectories of /etc/rc.d).</p>
</div>
<div class="section" id="verifying-a-source-installation">
<h3><a class="toc-backref" href="#id85">Verifying a Source Installation</a></h3>
<p>There are a number of things that you can do to check if the
installation (make install) went well. The fist is to check where
the system has installed apcupsd using '<tt class="docutils literal">which</tt>' and '<tt class="docutils literal">whereis</tt>'. On
my Red Hat system, you should get the following (lines preceded
with a $ indicate what you type):</p>
<pre class="literal-block">
$ which apcupsd
/sbin/apcupsd
$ whereis apcupsd
apcupsd: /sbin/apcupsd /etc/apcupsd /etc/apcupsd.conf
/etc/apcupsd.status /usr/man/man8/apcupsd.8.gz
/usr/man/man8/apcupsd.8
</pre>
<p>If you find an apcupsd in /usr/sbin, /usr/local/sbin, /usr/lib, or
another such directory, it is probably a piece of an old version of
apcupsd that you can delete. If you are in doubt, delete it, then
rerun the '<tt class="docutils literal">make install</tt>' to ensure that you haven't deleted
anything needed by the new apcupsd. Please note that the files
specified above assume the default installation locations.</p>
<p>As a final check that the '<tt class="docutils literal">make install</tt>' went well, you should
check your halt script (in /etc/rc.d on SUSE systems, and in
/etc/rc.d/init.d on Red Hat systems) to see that the appropriate
lines have been inserted in the correct place. Modification of the
halt script is important so that at the end of the shutdown
procedure, apcupsd will be called again to command the UPS to turn
off the power. This should only be done in a power failure
situation as indicated by the presence of the /etc/powerfail file,
and is necessary if you want your machine to automatically be
restarted when the power returns. On a Red Hat system, the lines
containing the <tt class="docutils literal"># <span class="pre">***apcupsd***</span></tt> should be inserted just
before the final halt command:</p>
<pre class="literal-block">
# Remount read only anything that's left mounted.
#echo "Remounting remaining filesystems (if any) readonly"
mount | awk '/ext2/ { print $3 }' | while read line; do
mount -n -o ro,remount $line
done
# See if this is a powerfail situation. # ***apcupsd***
if [ -f /etc/apcupsd/powerfail ]; then # ***apcupsd***
echo # ***apcupsd***
echo "APCUPSD will now power off the UPS" # ***apcupsd***
echo # ***apcupsd***
/etc/apcupsd/apccontrol killpower # ***apcupsd***
echo # ***apcupsd***
echo "Please ensure that the UPS has powered off before rebooting" # ***apcupsd***
echo "Otherwise, the UPS may cut the power during the reboot!!!" # ***apcupsd***
echo # ***apcupsd***
fi # ***apcupsd***
# Now halt or reboot.
echo "$message"
if [ -f /fastboot ]; then
echo "On the next boot fsck will be skipped."
elif [ -f /forcefsck ]; then
echo "On the next boot fsck will be forced."
fi
</pre>
<p>The purpose of modifying the system halt files is so that apcupsd
will be recalled after the system is in a stable state. At that
point, apcupsd will instruct the UPS to shut off the power. This is
necessary if you wish your system to automatically reboot when the
mains power is restored. If you prefer to manually reboot your
system, you can skip this final system dependent installation step
by specifying the <tt class="docutils literal"><span class="pre">disable-install-distdir</span></tt> option on the
'<tt class="docutils literal">./configure</tt>' command (see below for more details).</p>
<p>The above pertains to Red Hat systems only. There are significant
differences in the procedures on each system, as well as the
location of the halt script. Also, the information that is inserted
in your halt script varies from system to system. Other systems
such as Solaris require you the make the changes manually, which
has the advantage that you won't have any unpleasant surprises in
your halt script should things go wrong. Please consult the
specific system dependent README files for more details.</p>
<p>Please note that if you install from RPMs for a slave machine, you
will need to remove the changes that the RPM install script made
(similar to what is noted above) to the halt script. This is
because on a slave machine there is no connection to the UPS, so
there is no need to attempt to power off the UPS. That will be done
by the master.</p>
</div>
<div class="section" id="configure-options">
<h3><a class="toc-backref" href="#id86">Configure Options</a></h3>
<p>All the available <tt class="docutils literal">configure</tt> options can be printed by entering:</p>
<pre class="literal-block">
./configure --help
</pre>
<p>When specifying options for '<tt class="docutils literal">./configure</tt>', if in doubt, don't put
anything, since normally the configuration process will determine
the proper settings for your system. The advantage of these options
is that it permits you to customize your version of apcupsd. If you
save the '<tt class="docutils literal">./configure</tt>' command that you use to create apcupsd, you
can quickly reset the same customization in the next version of
apcupsd by simply re-using the same command.</p>
<p>The following command line options are available for <tt class="docutils literal">configure</tt>
to customize your installation.</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">--prefix=<var>path</var></span></kbd></td>
<td>This defines the directory for the
non-executable files such as the manuals.
The default is /usr.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--sbindir=<var>path</var></span></kbd></td>
<td>This defines the directory for
the executable files such as apcupsd.
The default is /sbin. You may
be tempted to place the executable files in /usr/sbin or
/usr/local/sbin. Please use caution here as these directories may
be unmounted during a shutdown and thus may prevent the <tt class="docutils literal">halt</tt>
script from calling apcupsd to turn off the UPS power. Though your
data will be protected, in this case, your system will probably not
be automatically rebooted when the power returns</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--enable-cgi</span></kbd></td>
<td>This enables the building of the
CGI programs that permit Web browser access to apcupsd data. This
option is not necessary for the proper execution of apcupsd.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--with-cgi-bin=<var>path</var></span></kbd></td>
</tr>
<tr><td> </td><td>The with-cgi-bin
configuration option allows you to define the directory where the
CGI programs will be installed. The default is /etc/apcupsd, which
is probably not what you want.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--enable-apcsmart</span></kbd></td>
</tr>
<tr><td> </td><td>Turns on generation of the APC Smart driver (default).</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--enable-dumb</span></kbd></td>
<td>Turns on generation of the dumb signalling driver code (default).</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--enable-usb</span></kbd></td>
<td>Turns on generation of the USB driver code. By default this is disabled.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--enable-net</span></kbd></td>
<td>Turns on generation of the NIS
network driver for slaves. For each slave, this is the only driver
needed. This driver works by reading the information from the the
configured master using the NIS (Network Information Services)
interface.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--enable-snmp</span></kbd></td>
<td>Turns on generation of the
SNMP driver. This driver accesses the UPS over the network using
SNMP. This is compatible only with UPSes equipped with an SNMP or
Web/SNMP management card. By default this is enabled.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--enable-net-snmp</span></kbd></td>
</tr>
<tr><td> </td><td>Turns on generation of the
obsolete NET-SNMP driver. This driver was the precursor to the current
snmp driver and is now obsolete. It is available as a fallback if the new
driver cannot be used for some reason. By default this is disabled.</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--enable-pcnet</span></kbd></td>
<td>Turns on generation of the
PCNET (PowerChute Network Shutdown) driver. This driver accesses
the UPS over the network using APC's custom protocol. This driver
can be used as an alternative to SNMP for UPSes equipped with a
modern Web/SNMP management card.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--enable-modbus</span></kbd></td>
</tr>
<tr><td> </td><td>Turns on generation of the MODBUS/RS232 driver (default)</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--enable-modbus-usb</span></kbd></td>
</tr>
<tr><td> </td><td>Turns on generation of the MODBUS/USB driver</td></tr>
<tr><td class="option-group">
<kbd><span class="option">--enable-test</span></kbd></td>
<td>This turns on a test driver
that is used only for debugging. By default it is disabled.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--enable-gapcmon</span></kbd></td>
</tr>
<tr><td> </td><td>This option enables building the GTK GUI front-end for
apcupsd. Building this package requires numerous GNOME libraries. The
default is disabled.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--enable-apcagent</span></kbd></td>
</tr>
<tr><td> </td><td>This option enables building the apcagent menubar application
on Mac OS X platforms. The default is disabled.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--with-libwrap=<var>path</var></span>, <span class="option">--with-libwrap</span></kbd></td>
</tr>
<tr><td> </td><td>This option when
enabled causes apcupsd to be built with the TCP WRAPPER library for
enhanced security. In most cases, the path is optional since
configure will determine where the libraries are on most systems.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--with-nologin=<var>path</var></span></kbd></td>
</tr>
<tr><td> </td><td>This option allows you
to specify where apcupsd will create the nologin file when logins
are prohibited. The default is /etc</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--with-pid-dir=<var>path</var></span></kbd></td>
</tr>
<tr><td> </td><td>This option allows you
to specify where apcupsd will create the process id (PID) file to
prevent multiple copies from running. The default is system
dependent but usually /var/run.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--with-log-dir=<var>path</var></span></kbd></td>
</tr>
<tr><td> </td><td>This option allows you
to specify where apcupsd will create the EVENTS and STATUS log
files. The default is /etc/apcupsd. This option simply sets the
default of the appropriate path in the apcupsd.conf file, which can
be changed at any later time.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--with-lock-dir=<var>path</var></span></kbd></td>
</tr>
<tr><td> </td><td>This option allows
you to specify where apcupsd will create the serial port lock file.
The default is system-dependent but usually /var/lock. This option
simply sets the appropriate path in the apcupsd.conf file, which
can be changed at any later time.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--with-pwrfail-dir=<var>path</var></span></kbd></td>
</tr>
<tr><td> </td><td>This option
allows you to specify where apcupsd will create the powerfail file
when a power failure occurs. The default is system dependent but
usually /etc.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--with-serial-dev=<var>device-name</var></span></kbd></td>
</tr>
<tr><td> </td><td>This
option allows you to specify where apcupsd will look for the serial
device that talks to the UPS. The default is system dependent, but
often /dev/ttyS0. This option simply sets the appropriate device
name in the apcupsd.conf file, which can be changed at any later
time.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--with-nis-port=<var>port</var></span></kbd></td>
</tr>
<tr><td> </td><td>This option allows
you to specify what port apcupsd will use for the Network
Information Server (the CGI programs). The default is system
dependent but usually 3551 because that port has been officially
assigned to apcupsd by the IANA. This option simply sets the
appropriate port in the apcupsd.conf file, which can be changed at
any later time.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--with-nisip=<var>ip-address</var></span></kbd></td>
</tr>
<tr><td> </td><td>This option allows
you to specify the value that will be placed on then NISIP
directive in the configuration file. The default is 0.0.0.0. No
checking is done on the value entered, so you must ensure that it
is a valid IP address.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--with-net-port=<var>port</var></span></kbd></td>
</tr>
<tr><td> </td><td>This option allows
you to specify what port apcupsd will use for Master and Slave
communications. The default is system dependent but usually 6666.
This option simply sets the appropriate port in the apcupsd.conf
file, which can be changed at any later time.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--with-upstype=<var>type</var></span></kbd></td>
</tr>
<tr><td> </td><td>This option allows you
to specify the type of UPS that will be connected to your computer.
The default is: smartups. This option simply sets the appropriate
UPS type in the apcupsd.conf file, which can be changed at any
later time.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--with-upscable=<var>cable</var></span></kbd></td>
</tr>
<tr><td> </td><td>This option allows
you to specify what cable you are using to connect to the UPS. The
default is: smart. This option simply sets the appropriate UPS
cable in the apcupsd.conf file, which can be changed at any later
time.</td></tr>
<tr><td class="option-group" colspan="2">
<kbd><span class="option">--disable-install-distdir</span></kbd></td>
</tr>
<tr><td> </td><td>This
option modifies the apcupsd Makefiles disable installation of the
distribution (platform) directory. Generally, this used to do a
full installation of apcupsd except the final modification of the
operating system files (normally /etc/rc.d/halt, etc.). This is
useful if your operating system is not directly supported by
apcupsd or if you want to run two copies of apcupsd on the same
system. This option can also be used by those of you who prefer to
manually reboot your system after a power failure or who do not
want to modify your system halt files.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="recommended-options-for-most-systems">
<h3><a class="toc-backref" href="#id87">Recommended Options for most Systems</a></h3>
<p>For most systems, we recommend the following options:</p>
<pre class="literal-block">
./configure --prefix=/usr --sbindir=/sbin --enable-usb
</pre>
<p>and you can optionally build and install the CGI programs as
follows:</p>
<pre class="literal-block">
./configure --prefix=/usr --sbindir=/sbin --enable-usb \
--enable-cgi --with-cgi-bin=/home/httpd/cgi-bin
</pre>
</div>
<div class="section" id="compilers-and-options">
<h3><a class="toc-backref" href="#id88">Compilers and Options</a></h3>
<p>Some systems require unusual options
for compilation or linking that the '<tt class="docutils literal">./configure</tt>' script does not
know about. You can specify initial values for variables by setting
them in the environment. Using a Bourne-compatible shell, you can
do that on the command line like this:</p>
<pre class="literal-block">
CFLAGS="-O2 -Wall" LDFLAGS= ./configure
</pre>
<p>Or on systems that have the <tt class="docutils literal">env</tt> program, you can do it like
this:</p>
<pre class="literal-block">
env CPPFLAGS=-I/usr/local/include LDFLAGS=-s ./configure
</pre>
<p>Or for example on the Sun Solaris system, you can use:</p>
<pre class="literal-block">
setenv CFLAGS -O2
setenv LDFLAGS -O
./configure
</pre>
<p>You can get a listing of all available options by doing:</p>
<pre class="literal-block">
./configure --help
</pre>
<p>or simply see the previous section of this manual.</p>
</div>
<div class="section" id="operating-system-specifics">
<h3><a class="toc-backref" href="#id89">Operating System Specifics</a></h3>
<p>With the exception of Linux SUSE and Linux Red Hat
systems used by the developers, we rely on users to help create
installation scripts and instructions as well as to test that
apcupsd runs correctly on their system. As you can imagine, most of
these people are system administrators rather than developers so
they are very busy and don't always have time to test the latest
releases. With that in mind, we believe that you will find that a
lot of very valuable work has been already done to make your
installation much easier (and probably totally automatic).</p>
<p>Below, you will find a list of operating systems for which we have
received installation files:</p>
<ul class="simple">
<li>Debian (see <a class="reference internal" href="#debian">Debian</a>)</li>
<li>FreeBSD (see <a class="reference internal" href="#freebsd">FreeBSD</a>)</li>
<li>HPUX (see <a class="reference internal" href="#hpux">HPUX</a>)</li>
<li>NetBSD (see <a class="reference internal" href="#netbsd">NetBSD</a>)</li>
<li>Mac OS X Darwin (see <a class="reference internal" href="#mac-os-x-darwin">Mac OS X Darwin</a>)</li>
<li>OpenBSD (see <a class="reference internal" href="#openbsd">OpenBSD</a>)</li>
<li>Red Hat (see <a class="reference internal" href="#red-hat-systems">Red Hat Systems</a>)</li>
<li>Slackware (see <a class="reference internal" href="#slackware">Slackware</a>)</li>
<li>SUSE (see <a class="reference internal" href="#suse">SUSE</a>)</li>
<li>Solaris (see <a class="reference internal" href="#sun-solaris">Sun Solaris</a>)</li>
<li>unknown (see <a class="reference internal" href="#unknown-system">Unknown System</a>)</li>
<li>Win32 (see <a class="reference internal" href="#windows-systems">Windows Systems</a>)</li>
</ul>
<div class="section" id="debian">
<h4><a class="toc-backref" href="#id90">Debian</a></h4>
<p>This port is complete and is being used by several users. Since Debian
build and install procedures are somewhat particular, we have put the extra
Debian information into the following two subdirectories:
<tt class="docutils literal">platforms/debian/examples</tt> and <tt class="docutils literal">platforms/debian/packageinfo</tt></p>
<p>You can also find the official Debian packages on the Debian site
at:</p>
<ul class="simple">
<li><a class="reference external" href="https://packages.debian.org/stable/apcupsd">https://packages.debian.org/stable/apcupsd</a></li>
<li><a class="reference external" href="https://packages.debian.org/testing/apcupsd">https://packages.debian.org/testing/apcupsd</a></li>
<li><a class="reference external" href="https://packages.debian.org/unstable/apcupsd">https://packages.debian.org/unstable/apcupsd</a></li>
</ul>
</div>
<div class="section" id="freebsd">
<h4><a class="toc-backref" href="#id91">FreeBSD</a></h4>
<p>This port is complete and is being used by several users.</p>
<p>You will need to install and use GNU make (aka gmake) instead of the
BSD make supplied with the system.</p>
<p>On the FreeBSD OS, there is no known way for a user program to get
control when all the disks are synced. This is needed for apcupsd
to be able to issue the killpower command to the UPS so that the
UPS shuts off the power. To accomplish the same thing on FreeBSD
systems, make sure you have a SmartUPS and that your UPS shutdown
grace period is set sufficiently long so that you system will power
down (usually 2 minutes), the use the <tt class="docutils literal"><span class="pre">--kill-on-powerfail</span></tt> option
on the apcupsd command line.</p>
</div>
<div class="section" id="hpux">
<h4><a class="toc-backref" href="#id92">HPUX</a></h4>
<p>Status of this port is unknown.</p>
</div>
<div class="section" id="netbsd">
<h4><a class="toc-backref" href="#id93">NetBSD</a></h4>
<p>You will need to install and use GNU make (aka gmake) instead of the
BSD make supplied with the system.</p>
</div>
<div class="section" id="mac-os-x-darwin">
<h4><a class="toc-backref" href="#id94">Mac OS X Darwin</a></h4>
<p>On OS X (Darwin), apcupsd can be built with <tt class="docutils literal">configure</tt> defaults.
The USB driver can be enabled, as per the directions on <a class="reference internal" href="#mac-os-x-darwin-usb-configuration">Mac OS X (Darwin)
USB Configuration</a> Apcupsd <em>may</em> be usable
on OS X with a smart serial device, but certainly <em>does</em> work as a
NIS client or using a USB interface.</p>
<p>The startup information will be installed in
<tt class="docutils literal">/Library/StartupItems/apcupsd</tt> which is part of darwin's
SystemStartup.</p>
</div>
<div class="section" id="openbsd">
<h4><a class="toc-backref" href="#id95">OpenBSD</a></h4>
<p>You will need to install and use GNU make (aka gmake) instead of the
BSD make supplied with the system.</p>
<p>Ensure that you read
the distributions/openbsd/README file before running apcupsd. There
are some critical differences in how the OpenBSD implementation
operates when the UPS batteries are exhausted. Failure to take this
into account may result in the system not being fully halted when
power is lost.</p>
</div>
<div class="section" id="red-hat-systems">
<h4><a class="toc-backref" href="#id96">Red Hat Systems</a></h4>
<p>Red Hat systems are
fully supported, and by following the standard installation
instructions given above, you should experience few or no
problems.</p>
</div>
<div class="section" id="slackware">
<h4><a class="toc-backref" href="#id97">Slackware</a></h4>
<p>Slackware
systems are fully supported, and by following the standard
installation instructions given above, you should experience few or
no problems.</p>
</div>
<div class="section" id="suse">
<h4><a class="toc-backref" href="#id98">SUSE</a></h4>
<p>SUSE systems are fully
supported, and by following the standard installation instructions
given above, you should experience few or no problems.</p>
</div>
<div class="section" id="sun-solaris">
<h4><a class="toc-backref" href="#id99">Sun Solaris</a></h4>
<p>Please read this before attempting to compile or install the beta
software. It contains important information that will make your
efforts easier.</p>
<p>Before running '<tt class="docutils literal">./configure</tt>', please be sure that you do not have
/usr/ucb on your path. This may cause the <tt class="docutils literal">configure</tt> to choose
the wrong shutdown program. If <tt class="docutils literal">configure</tt> detects that /usr/usb
is on your path, it will print a warning message. Please follow the
advice to avoid shutdown problems.</p>
<p>Your normal UNIX user ID must own the source tree directories, and
you must have the normal development tools in your path. This
includes make, the compiler, the M4 preprocessor, the linker, and
ar or ranlib. If the user you are logged in as can compile and link
a C program from a source file, then you have all the required
tools available.</p>
<p>You will want to install the executables in a directory that
remains mounted during the shutdown. Solaris will unmount almost
everything except the root directories. Since the ability to power
the UPS off requires access to the executable programs, they need
to be in a directory that will never be unmounted. And since they
should also be in a directory that normal users cannot get into,
/sbin is the default. However, please be aware that if you want to
follow Sun's filesystem conventions you would use the following:</p>
<pre class="literal-block">
./configure \
--prefix=/opt/apcupsd \
--sbindir=/etc/opt/apcupsd/sbin \
--sysconfdir=/etc/opt/apcupsd \
--with-cgi-bin=/opt/apcupsd/cgi-bin
</pre>
<p>The way to setup the /sbin directory as the executables directory
is to pass configure the <tt class="docutils literal"><span class="pre">--sbindir=/sbin</span></tt> option. No other
arguments should be required, and your setup and platform should be
detected automatically by configure.</p>
<p>Once you have run configure, you will need to do a '<tt class="docutils literal">gmake</tt>'. Once
the make has completed with no errors, you must su to root to
complete the install. After the su, you may not have a path to the
make program anymore. In that case, you should do the '<tt class="docutils literal">gmake
install</tt>' step as:</p>
<pre class="literal-block">
gmake install
</pre>
<p>Once the install completes, you must edit the /sbin/rc0 script as
detailed below, then exit from the su'ed shell.</p>
<p>In order to support unattended operation and shutdown during a
power failure, it's important that the UPS remove power after the
shutdown completes. This allows the unattended UPS to reboot the
system when power returns by re-powering the system. Of course, you
need autoboot enabled for your system to do this, but all Solaris
systems have this by default. If you have disabled this on your
system, please re-enable it.</p>
<p>To get the UPS to remove power from the system at the correct time
during shutdown, i.e., after the disks have done their final sync,
we need to modify a system script. This script is /sbin/rc0.</p>
<p>We do not have access to every version of Solaris, but we believe
this file will be almost identical on every version. Please let us
know if this is not true.</p>
<p>At the very end of the /sbin/rc0 script, you should find lines just
like the following:</p>
<pre class="literal-block">
# unmount file systems. /usr, /var and /var/adm are not unmounted by umountall
# because they are mounted by rcS (for single user mode) rather than
# mountall.
# If this is changed, mountall, umountall and rcS should also change.
/sbin/umountall
/sbin/umount /var/adm >/dev/null 2>\&1
/sbin/umount /var >/dev/null 2>\&1
/sbin/umount /usr >/dev/null 2>\&1
echo 'The system is down.'
</pre>
<p>We need to insert the following lines just before the last 'echo':</p>
<pre class="literal-block">
#see if this is a powerfail situation
if [ -f /etc/apcupsd/powerfail ]; then
echo
echo "APCUPSD will power off the UPS"
echo
/etc/apcupsd/apccontrol killpower
echo
echo "Please ensure that the UPS has powered off before rebooting"
echo "Otherwise, the UPS may cut the power during the reboot!!!"
echo
fi
</pre>
<p>We have included these lines in a file called rc0.solaris in the
distributions/sun subdirectory of the source tree. You can cut and
paste them into the /sbin/rc0 file at the correct place, or yank
and put them using vi or any other editor. Note that you must be
root to edit this file.</p>
<p>You must be absolutely sure you have them in the right place. If
your /sbin/rc0 file does not look like the lines shown above, do
not modify the file. Instead, email a copy of the file to the
maintainers, and we will attempt to figure out what you should do.
If you mess up this file, the system will not shut down cleanly,
and you could lose data. Don't take the chance.</p>
<p>You will then need to make the normal changes to the
/etc/apcupsd/apcupsd.conf file. This file contains the
configuration settings for the package. It is important that you
set the values to match your UPS model and cable type, and the
serial port that you have attached the UPS to. People have used
both /dev/ttya and /dev/ttyb with no problems. You should be sure
that logins are disabled on the port you are going to use,
otherwise you will not be able to communicate with the UPS. If you
are not sure that logins are disabled for the port, run the
'admintool' program as root, and disable the port. The 'admintool'
program is a GUI administration program, and required that you are
running CDE, OpenWindows, or another XWindows program such as KDE.</p>
<p>Solaris probes the serial ports during boot, and during this
process, it toggles some handshaking lines used by dumb UPSes. As a
result, particularly for simple signalling "dumb" UPSes it seems to
kick it into a mode that makes the UPS think it's either in a
calibration run, or some self-test mode. Since at this point we are
really not communicating with the UPS, it's pretty hard to tell
what happened. But it's easy to prevent this, and you should.
Disconnect the UPS, and boot the system. When you get to a login
prompt, log in as root. Type the following command:</p>
<pre class="literal-block">
eeprom com1-noprobe=true
</pre>
<p>or</p>
<pre class="literal-block">
eeprom com2-noprobe=true
</pre>
<p>depending on which com port your UPS is attached to. Then sync and
shutdown the system normally, reattach the UPS, and reboot. This
should solve the problem. However, we have some reports that recent
versions of Solaris (7 & 8) appear to have removed this eeprom
option and there seems to be no way to suppress the serial port
probing during boot.</p>
<p>At this point, you should have a complete installation. The daemon
will load automatically at the next boot. Watch for any error
messages during boot, and check the event logs in /etc/apcupsd. If
everything looks OK, you can try testing the package by removing
power from the UPS. NOTE! if you have a voltage-signalling UPS,
please run the first power tests with your computer plugged into
the wall rather than into the UPS. This is because dumb serial-port
UPSes have a tendency to power off if your configuration or cable
are not correct.</p>
<p>As a user, your input is very helpful in solving problems with the
package, and providing suggestions and future directions for the
development of the package. We are striving to provide a useful
package that works across all platforms, and welcome your
feedback.</p>
</div>
<div class="section" id="unknown-system">
<h4><a class="toc-backref" href="#id100">Unknown System</a></h4>
<p>During the '<tt class="docutils literal">./configure</tt>', if apcupsd does not find one of the systems for
which it has specific installation programs, it will set the
Operating System to <tt class="docutils literal">unknown</tt> and will use the incomplete
installation scripts that are in <tt class="docutils literal">platforms/unknown</tt>. You
will be on your own, or you can ask the developers list
(<a class="reference external" href="mailto:apcupsd-users@lists.sourceforge.net">apcupsd-users@lists.sourceforge.net</a>) for installation
instructions. This directory also contains a hint file for Linux
From Scratch, which could be helpful for other systems as well.</p>
</div>
<div class="section" id="windows-systems">
<h4><a class="toc-backref" href="#id101">Windows Systems</a></h4>
<p>Appropriate scripts
(actually Windows batch files) are included with the Apcupsd Win32
installer package.</p>
</div>
</div>
</div>
<div class="section" id="after-installation">
<h2><a class="toc-backref" href="#id102">After Installation</a></h2>
<div class="section" id="checking-your-configuration-file">
<h3><a class="toc-backref" href="#id103">Checking Your Configuration File</a></h3>
<p>Once you have installed apcupsd,
either from a binary package or by building from source, your next
step should be to inspect your <tt class="docutils literal">/etc/apcupsd/apcupsd.conf</tt> file to
make sure it is valid.</p>
<p>You can read the complete reference on configuration directives
(<a class="reference internal" href="#configuration-directive-reference">Configuration Directive Reference</a>), but if you are
setting up a normal standalone configuration you should only need
to check (and possibly fix) the first three items listed below.</p>
<p>Your <tt class="docutils literal">UPSTYPE</tt> should be the UPS's protocol type: dumb, apcsmart,
usb, net, pcnet, or snmp. Your <tt class="docutils literal">UPSCABLE</tt> should be the type of cable
you are using.</p>
<p><tt class="docutils literal">DEVICE</tt> should be set to the path of the device node
(usually in /dev) to use to communicate with the UPS. This is used primarily
for serial port connections. If you have a USB device, it is better not to
specify a <tt class="docutils literal">DEVICE</tt> directive by leaving it black or commenting it out.
Apcupsd will automatically search for your device in the standard places.
If you specify a <tt class="docutils literal">DEVICE</tt>, it should be the name of the device that
apcupsd is to use to communicate with the UPS.</p>
<p>If the first time you execute apcupsd, you get a message to the
effect that the Apcupsd USB driver is missing, it means that you
most likely forgot to put <tt class="docutils literal"><span class="pre">--enable-usb</span></tt> on your '<tt class="docutils literal">./configure</tt>'
command line.</p>
<p>The <a class="reference internal" href="#configuration-examples">Configuration Examples</a> chapter of this manual provides
the essential characteristics of each main type of configuration
file. After those elements are correct, apcupsd should run, and
then it is only a matter of customization of your setup.</p>
</div>
<div class="section" id="arranging-for-reboot-on-power-up">
<h3><a class="toc-backref" href="#id104">Arranging for Reboot on Power-Up</a></h3>
<p>The final consideration for a automatic reboot after a full power down
is to ensure that your computer will automatically reboot when the
power is restored.</p>
<p>This is not the normal behavior of most computers as shipped from
the factory. Normally after the power is cut and restored, you must
explicitly press a button for the power to actually be turned on.
You can test your computer by powering it down; shutting off the
power (pull the plug); then plugging the cord back in. If your
computer immediately starts up, good. There is nothing more to do.</p>
<p>If your computer does not start up, manually turn on the power (by
pressing the power on button) and enter your computer's SETUP
program (often by pressing DEL during the power up sequence;
sometimes by pressing F10). You must then find and change the
appropriate configuration parameter to permit instant power on.</p>
<p>Normally, this is located under the <tt class="docutils literal">BOOT</tt> menu item, and will be
called something such as <tt class="docutils literal">Restore on AC/Power Loss</tt> or <tt class="docutils literal"><span class="pre">Full-On</span></tt>.
The exact words will vary according to the ROM BIOS provider.
Generally you will have three options: <tt class="docutils literal">Last State</tt>, <tt class="docutils literal">Power On</tt>,
and <tt class="docutils literal">Power Off</tt>. Although <tt class="docutils literal">Last State</tt> should normally work, we
recommend setting your computers to <tt class="docutils literal">Power On</tt>. This means that
whenever the power is applied they are on. The only way to shut
them off is to pull the plug or to have a special program that
powers them off (/sbin/poweroff on Linux systems).</p>
<p>If after making all the changes suggested above, you cannot get
your computer to automatically reboot, you might examine your halt
script (/etc/rc.d/init.d/halt in the case of Red Hat Linux) and see
if the final line that performs the halt or reboot contains the
<tt class="docutils literal"><span class="pre">-p</span></tt> option for powering down the computer. It should not with the
logic used by apcupsd, but if it does, the <tt class="docutils literal"><span class="pre">-p</span></tt> option could cause
your computer to power off while the UPS is still suppling power
(i.e. before the UPS kills the power). Depending on the setting of
your BIOS, it may prevent your computer from restarting when the
power returns. As already mentioned, this should not apply, but in
case of problems it is worth a try.</p>
</div>
<div class="section" id="making-sure-apcupsd-is-running">
<h3><a class="toc-backref" href="#id105">Making sure apcupsd Is Running</a></h3>
<p>The simplest way to invoke apcupsd is from the command line by entering:</p>
<pre class="literal-block">
/sbin/apcupsd
</pre>
<p>To do so, you must be root. However, normally, you will want
apcupsd started automatically when your system boots. On some
systems with installation support (e.g. SUSE and Red Hat), the
installation procedure will create a script file that you will be
automatically invoked when your system reboots. On other systems,
you will have to invoke apcupsd from your rc.local script.</p>
<p>On Red Hat systems, this script file that automatically invokes
apcupsd on system start and stops is <tt class="docutils literal">/etc/rc.d/init.d/apcupsd</tt></p>
<p>To start apcupsd manually (as you will probably do immediately
following the installation), enter the following:</p>
<pre class="literal-block">
/etc/rc.d/init.d/apcupsd start
</pre>
<p>To understand how this file is automatically invoked at system
startup and shutdown, see the man pages for <tt class="docutils literal">chkconfig(8)</tt>.</p>
<p>On SUSE systems, the script file that automatically invokes apcupsd
on system start and stops is <tt class="docutils literal">/etc/rc.d/apcupsd</tt>.</p>
<p>To start apcupsd manually (as you will probably do immediately
following the installation), enter the following:</p>
<pre class="literal-block">
/etc/rc.d/apcupsd start
</pre>
<p>Normally, when properly installed, apcupsd will be started and
stopped automatically by your system. Unfortunately, the details
are different for each system. Below, we give the commands for
selected systems. Alternatively, there are simple stopapcupsd and
startapcupsd scripts in the examples directory, or you can modify
one of the scripts in the distributions directory to meet your
needs.</p>
<p>To stop apcupsd you can do the following:</p>
<p>On Red Hat systems:</p>
<pre class="literal-block">
/etc/rc.d/init.d/apcupsd stop
</pre>
<p>On SUSE systems:</p>
<pre class="literal-block">
/etc/rc.d/apcupsd stop
</pre>
<p>Please see the <a class="reference internal" href="#testing-apcupsd">Testing Apcupsd</a> chapter for more details on insuring
that apcupsd is running properly.</p>
</div>
</div>
<div class="section" id="configuration-examples">
<h2><a class="toc-backref" href="#id106">Configuration Examples</a></h2>
<div class="section" id="a-simple-usb-configuration">
<h3><a class="toc-backref" href="#id107">A Simple USB Configuration</a></h3>
<p>If you have a USB UPS, the essential elements of your apcupsd.conf file
should look like the following:</p>
<pre class="literal-block">
## apcupsd.conf v1.1 ##
UPSCABLE usb
UPSTYPE usb
DEVICE
LOCKFILE /var/lock
UPSCLASS standalone
UPSMODE disable
</pre>
<p>Notice that we have not specified a device. In doing so, apcupsd
will try all the well known USB ports. We strongly recommend you
use this (empty device address) form unless you have a good reason
to do otherwise.</p>
<p>Please use the explicit specifications of a device only if you know
exactly what you are doing. In general, it is much easier to let
apcupsd find the device itself.</p>
<p>Please see <a class="reference internal" href="#usb-configuration">USB Configuration</a> for detailed help
on setting up your system to work with a USB UPS.</p>
</div>
<div class="section" id="a-simple-configuration-for-a-serial-smartups">
<h3><a class="toc-backref" href="#id108">A Simple Configuration for a Serial SmartUPS</a></h3>
<p>If you have a Smart UPS
using the serial cable supplied by APC, or you build a CUSTOM SMART cable
outlined in the cables chapter, a very simple configuration file
would look like the following:</p>
<pre class="literal-block">
## apcupsd.conf v1.1 ##
UPSCABLE smart
UPSTYPE apcsmart
DEVICE /dev/ttyS0
LOCKFILE /var/lock
UPSCLASS standalone
UPSMODE disable
</pre>
<p>Normally you would have many more configuration directives to
completely customize your installation, but this example shows you
the minimum required.</p>
</div>
<div class="section" id="a-simple-configuration-for-a-simple-signaling-or-dumb">
<h3><a class="toc-backref" href="#id109">A Simple Configuration for a Simple Signaling or Dumb</a></h3>
<p>If you have a simple signaling
or dumb UPS such as a BackUPS, you will need to know exactly what
cable you have and specify it on the UPSCABLE directive. Please see
the list of UPSes versus cables in the beginning of this document
for more information. The cable number is normally stamped in the
plastic at one end of the cable. If you specify the wrong cable, it
is very likely that at the first power failure, your computer will
be immediately shutdown. This is an unfortunate consequence of the
dumb signaling mode. To avoid this, first replace
/etc/apcupsd/apccontrol with safe.apccontrol found in the
examples directory, then test until everything works correctly.
Once you have the correct cable, be sure to remember to reinstall
the correct apccontrol file and test that your computer is
correctly shutdown during a power failure.</p>
<pre class="literal-block">
## apcupsd.conf v1.1 ##
UPSCABLE (number of cable you have)
UPSTYPE dumb
DEVICE /dev/ttyS0
LOCKFILE /var/lock
UPSCLASS standalone
UPSMODE disable
</pre>
<p>If your cable does not have low battery detection, as is the case
with some older models, you will also need to define <tt class="docutils literal">TIMEOUT nnn</tt>
where you set <tt class="docutils literal">nn</tt> to be the number of seconds on a power failure
after which a shutdown is effected.</p>
<p>Normally you would have many more configuration directives to
completely customize your installation, but this example shows you
the minimum required.</p>
</div>
<div class="section" id="nis-server-client-configuration-using-the-net-driver">
<h3><a class="toc-backref" href="#id110">NIS Server/Client Configuration Using the Net Driver</a></h3>
<p>NIS (Network Information Server) mode allows for communication
between instances of apcupsd running on different hosts. Only one
of those hosts, the server, needs to talk to the UPS directly. The
others, clients, obtain information about the state of the UPS by
querying the server. NIS is <em>not</em> related to Sun's NIS/YP
services.</p>
<p>NIS clients and servers require that apcupsd be compiled with the
Net Driver <tt class="docutils literal"><span class="pre">--enable-net</span></tt>. This is typically enabled by default.</p>
<p>The NIS server is connected to the UPS and should be configured
exactly as a standalone configuration, but with <tt class="docutils literal">NETSERVER on</tt>.
In all other respects, the server should be configured in
standalone mode. You may also set the NIS server specific options
<tt class="docutils literal">NISIP</tt> to restrict which IP address of the server which apcupsd
listens on. The default, 0.0.0.0, means to list on all of the
server host's IP addresses; <tt class="docutils literal">NISPORT</tt> (default 3551) to set which
TCP port the server listens on; and <tt class="docutils literal">EVENTSFILE</tt> and
<tt class="docutils literal">EVENTSFILEMAX</tt> to provide information about the last few events
to clients. You may also need to modify your firewall rules on the
server's host to allow traffic to the <tt class="docutils literal">NISPORT</tt>.</p>
<p>For the NIS client computer, you will have a configuration that
looks something like what follows. What is important is that you
get the information from an <tt class="docutils literal">UPSCABLE ether</tt> with <tt class="docutils literal">UPSTYPE
net</tt> over the network and you must specify the address of
a NIS server using <tt class="docutils literal">DEVICE</tt>. The client apcupsd will then poll
the NIS server specified in <tt class="docutils literal">DEVICE</tt> every <tt class="docutils literal">POLLTIME</tt> seconds
(formerly <tt class="docutils literal">NETTIME</tt>).</p>
<pre class="literal-block">
## apcupsd.conf v1.1 ##
UPSCABLE ether
UPSTYPE net
LOCKFILE /var/lock
DEVICE server-network-address:3551
UPSCLASS standalone
UPSMODE disable
POLLTIME 10
</pre>
<p>The <tt class="docutils literal">DEVICE</tt> is set to <tt class="docutils literal"><span class="pre">server-address:port</span></tt>, where
<tt class="docutils literal"><span class="pre">server-address</span></tt> is the fully qualified domain name or IP address
of the apcupsd NIS server, and <tt class="docutils literal">port</tt> is the <tt class="docutils literal">NISPORT</tt> that the
server is listening on. The default is 3551, but older versions of
apcupsd used port 7000.</p>
<p>If you set <tt class="docutils literal">POLLTIME</tt> too large, your client may not see the
change in state of the NIS server before the server has shutdown.
Normally, you have at least 30 seconds of grace time between the
time the NIS server decides to shutdown and the time it no longer
responds. Your slave must poll during this interval.</p>
<p>Any client run using the Net driver will shutdown when its own
timers expire or when the NIS server shuts down, whichever occurs
first. This means that if you want the slave to shutdown before the
server, you need only set <tt class="docutils literal">BATTERYLEVEL</tt>, <tt class="docutils literal">MINUTES</tt> or
<tt class="docutils literal">TIMEOUT</tt> on the client for a faster shutdown than the values
defined on the NIS server. This can often be useful if the slave is
less important than the master and you wish to reduce battery power
consumption so that the master can remain up longer during a power
outage.</p>
<p>NIS clients work principally by reading the STATFLAG record that is
sent by the NIS server (present in the output of apcaccess). The
low 16 bits are the standard APC status flag, and the upper 16 bits
represent the internal state of apcupsd, so the slave can see when
the power fails and know when to shutdown.</p>
<p>It would be possible to have a client also work as a server, but
that would increase the delay of information getting from the UPS
to the secondary client.</p>
<div class="section" id="differences-between-nis-client-server-and-the-old-now-removed-master-slave-modes">
<h4><a class="toc-backref" href="#id111">Differences between NIS Client/Server and the old (now removed) Master/Slave modes</a></h4>
<p>The difference between the NIS mode and the removed master/slave
mode is that the NIS server has no explicit knowledge of the
slaves. The NIS server makes its information available via the net
(NIS), and the NIS slaves read it. When the NIS server is going to
shutdown, it makes the information available to any NIS slave that
polls it, but the NIS server does not explicitly call each NIS
slave as is the case in the Master/Slave networking described
several sections above.</p>
<p>Think of the difference as push (Master/Slave) vs. pull
(NIS-based). In the case of M/S, the master makes all the shutdown
decisions and notifies the slaves when they are to shut down or
when some other interesting event happens. The slaves just do
whatever the master says, whenever the master says to. On the other
hand, with the NIS-based network config you basically "publish" the
UPS status from one server and then your clients view that status
and make their own decisions.</p>
</div>
</div>
<div class="section" id="powerchute-network-shutdown-driver-pcnet">
<h3><a class="toc-backref" href="#id112">PowerChute Network Shutdown Driver (PCNET)</a></h3>
<p>As of 3.14, Apcupsd supports the PowerChute Network Shutdown
protocol. This is an alternative to SNMP for use with APC's AP9617
family of network smartslot modules. Note that the older AP9606
modules do <strong>not</strong> support PCNET.</p>
<p>To enable PCNET support, configure with the <tt class="docutils literal"><span class="pre">--enable-pcnet</span></tt>
flag. This is typically enabled by default.</p>
<p>The required apcupsd.conf settings are straightforward:</p>
<pre class="literal-block">
## apcupsd.conf v1.1 ##
UPSCABLE ether
UPSTYPE pcnet
LOCKFILE /var/lock
DEVICE ipaddr:user:passphrase
UPSCLASS standalone
UPSMODE disable
</pre>
<p>The <tt class="docutils literal">DEVICE</tt> setting specifies the IP address of the UPS as well
as the username and authentication passphrase to use. Note that the
username and passphrase are <strong>not</strong> the Web/SNMP login credentials.
They are separate settings. The default username on a new card is
"<tt class="docutils literal">apc</tt>" and the default passphrase is "<tt class="docutils literal">admin user phrase</tt>". To change
the passphrase, log in to the Web UI and go to the UPS tab, then to
PowerChute -> Configuration. (This assumes firmware v3.3.1. Other
versions may place the setting elsewhere.) <em>The password must be a
minimum of 15 characters long.</em> The web UI will silently ignore
shorter passwords and does not give an error message. There is no
apparent way to change the username.</p>
<p>Note that you may leave <tt class="docutils literal">DEVICE</tt> blank and Apcupsd will accept
information from any PCNET UPS on the network,
<strong>however it will be very insecure since an attacker could easily send packets
crafted to cause your server to shut down</strong>.
Using the <tt class="docutils literal">ipaddr</tt>, <tt class="docutils literal">user</tt>, and <tt class="docutils literal">passphrase</tt> will prevent this behavior.</p>
<p>You may need to take steps to ensure networking stays active during
your OS's shutdown sequence in order for the PCNET driver to power
off the UPS (the so-called "killpower" operation). On a Linux
distro, you can use commands such as...</p>
<pre class="literal-block">
chkconfig --level 0 network on
chkconfig --level 0 iptables on
</pre>
<p>...to make sure networking stays up.</p>
</div>
<div class="section" id="modbus-driver">
<h3><a class="toc-backref" href="#id113">MODBUS Driver</a></h3>
<p>MODBUS is APC's replacement for the aging 'apcsmart' (aka UPS-Link)
protocol. It is recommended for modern (ex: SMT series) Smart-UPS models.
As of 3.14.11, apcupsd supports the MODBUS protocol over RS232 serial
interfaces. As of 3.14.13, apcupsd supports the MODBUS protocol over USB.</p>
<p>Not all APC UPSes support MODBUS. New 2013 year Smart-UPS models are likely to
support it out-of-the-box and firmware updates are available for some older
models. APC/Schneider tech support is your best point of contact for determining
if a certain model will support MODBUS. That said, APC knowledge base article
FA164737 indicates MODBUS support is available for the majority of the SMC,
SMT, and SMX model lines.</p>
<p>The required apcupsd.conf settings for MODBUS are straightforward.</p>
<p>For MODBUS serial RS232:</p>
<blockquote>
<pre class="literal-block">
## apcupsd.conf v1.1 ##
UPSCABLE smart
UPSTYPE modbus
DEVICE /dev/ttyS0
LOCKFILE /var/lock
UPSCLASS standalone
UPSMODE disable
</pre>
<p>The <tt class="docutils literal">DEVICE</tt> setting identifies the serial port to which the UPS is connected.
This can take the form of <tt class="docutils literal">COM1</tt>, etc. on Windows or <tt class="docutils literal">/dev/XXX</tt> on UNIX
systems.</p>
<p>You should use the APC-supplied serial cable (P/N 940-0625A) that ships with
the UPS. Other 'smart' type cables may work, but only 940-0625A has been
formally tested at this time.</p>
</blockquote>
<p>For MODBUS USB:</p>
<blockquote>
<pre class="literal-block">
## apcupsd.conf v1.1 ##
UPSCABLE usb
UPSTYPE modbus
DEVICE
LOCKFILE /var/lock
UPSCLASS standalone
UPSMODE disable
</pre>
<p>The <tt class="docutils literal">DEVICE</tt> setting can be left blank or, optionally, set to the serial
number of the UPS. If <tt class="docutils literal">DEVICE</tt> is blank, apcupsd will attach to the first
APC UPS it finds, otherwise it will attach to the specific UPS identified by
the serial number.</p>
</blockquote>
<p>Note that <em>most UPSes ship with MODBUS support disabled by default</em>. You must
use the UPS's front panel menu to enable MODBUS protocol support before apcupsd
will be able to communicate with the UPS. You may need to enable the "Advanced"
menu option before the MODBUS protocol option will be visible.</p>
</div>
</div>
<div class="section" id="testing-apcupsd">
<h2><a class="toc-backref" href="#id114">Testing Apcupsd</a></h2>
<p>The following testing procedures apply for the
most part to SmartUPSes, whether USB or serial. If you have a
dumb voltage-signalling UPS, your testing procedures will be
somewhat different, and you should see the section on Testing
Serial UPSes (see <a class="reference internal" href="#testing-serial-line-upses">Testing Serial-Line UPSes</a>).</p>
<div class="section" id="process-status-test">
<h3><a class="toc-backref" href="#id115">Process-Status Test</a></h3>
<p>After you start apcupsd, execute the following command:</p>
<pre class="literal-block">
ps fax
</pre>
<p>or the equivalent for your system. You should see something similar
to the following output.</p>
<pre class="literal-block">
632 ? S 0:00 /sbin/apcupsd -f /etc/apcupsd/apcupsd.conf
841 ? S 0:00 \_ /sbin/apcupsd -f /etc/apcupsd/apcupsd.conf
842 ? S 0:00 \_ /sbin/apcupsd -f /etc/apcupsd/apcupsd.conf
</pre>
<p>This indicates that apcupsd is up and running and has started the
two standard threads in addition to the main thread.</p>
<p>If you see only one instance of apcupsd running, don't worry about
it as this is normal on most non-Linux systems, and on Linux 2.6.x
kernels.</p>
<p>If you do not find that apcupsd is in the above list, the most
likely problem is a configuration file glitch. If no messages were
printed, you should check your system log (normally
<tt class="docutils literal">/var/log/messages</tt>) where you will find one or messages indicating
the nature of the problem.</p>
</div>
<div class="section" id="logging-test">
<h3><a class="toc-backref" href="#id116">Logging Test</a></h3>
<p>Once you have established that the proper processes are running, do
a tail of the system log file, normally <tt class="docutils literal">/var/log/messages</tt>:</p>
<pre class="literal-block">
tail /var/log/messages
</pre>
<p>You should see output that looks similar to the following:</p>
<pre class="literal-block">
Dec 5 17:01:05 matou apcupsd[5917]: apcupsd 3.7.2 startup succeeded
</pre>
<p>These messages should also appear in the temporary file
(<tt class="docutils literal">/etc/apcupsd/apcupsd.events</tt>) if you are using the default
configuration file. If you have installed the RPM, they will
probably be in <tt class="docutils literal">/var/log/apcupsd.events</tt>.</p>
</div>
<div class="section" id="apcaccess-test">
<h3><a class="toc-backref" href="#id117">apcaccess Test</a></h3>
<p>This test consists of running <tt class="docutils literal">apcaccess</tt> to see if apcupsd is properly
updating its internal variables. Please note that you must enable
the apcupsd Network Information Server in your configuration file
for <tt class="docutils literal">apcaccess</tt> to work. This is done by setting:</p>
<pre class="literal-block">
NETSERVER on
NISPORT 3551
</pre>
<p>in your <tt class="docutils literal">apcupsd.conf</tt> file.</p>
<p>To run the apcaccess test, use the following command:</p>
<pre class="literal-block">
apcaccess status
</pre>
<p>Depending on the type of UPS you have, you will get slightly
different output, but an example For a Smart-UPS is as follows:</p>
<pre class="literal-block">
APC : 001,048,1088
DATE : Fri Dec 03 16:49:24 EST 1999
HOSTNAME : daughter
RELEASE : 3.7.2
CABLE : APC Cable 940-0024C
MODEL : APC Smart-UPS 600
UPSMODE : Stand Alone
UPSNAME : SU600
LINEV : 122.1 Volts
MAXLINEV : 123.3 Volts
MINLINEV : 122.1 Volts
LINEFREQ : 60.0 Hz
OUTPUTV : 122.1 Volts
LOADPCT : 32.7 Percent Load Capacity
BATTV : 26.6 Volts
BCHARGE : 095.0 Percent
MBATTCHG : 15 Percent
TIMELEFT : 19.0 Minutes
MINTIMEL : 3 Minutes
SENSE : Medium
DWAKE : 000 Seconds
DSHUTD : 020 Seconds
LOTRANS : 106.0 Volts
HITRANS : 129.0 Volts
RETPCT : 010.0 Percent
STATFLAG : 0x08 Status Flag
STATUS : ONLINE
ITEMP : 34.6 C Internal
ALARMDEL : Low Battery
LASTXFER : Unacceptable Utility Voltage Change
SELFTEST : NO
STESTI : 336
DLOWBATT : 05 Minutes
DIPSW : 0x00 Dip Switch
REG1 : N/A
REG2 : N/A
REG3 : 0x00 Register 3
MANDATE : 03/30/95
SERIALNO : 13035861
BATTDATE : 05/05/98
NOMOUTV : 115.0
NOMBATTV : 24.0
HUMIDITY : N/A
AMBTEMP : N/A
EXTBATTS : N/A
BADBATTS : N/A
FIRMWARE : N/A
APCMODEL : 6TD
END APC : Fri Dec 03 16:49:25 EST 1999
</pre>
<p>For a simple signaling or dumb UPS such as BackUPS, your output
will be very minimal as follows:</p>
<pre class="literal-block">
APC : 001,012,0319
DATE : Mon Feb 18 09:11:50 CST 2002
RELEASE : 3.8.5
UPSNAME : UPS_IDEN
CABLE : APC Cable 940-0128A
MODEL : BackUPS
UPSMODE : Stand Alone
STARTTIME: Mon Feb 18 09:11:45 CST 2002
LINEFAIL : OK
BATTSTAT : OK
STATFLAG : 0x008 Status Flag
END APC : Mon Feb 18 09:15:01 CST 2002
</pre>
<p>If you see the above output, it is a good sign that apcupsd is
working. Assuming that the output looks reasonable, check the
following variables:</p>
<dl class="docutils">
<dt><tt class="docutils literal">LINEV</tt></dt>
<dd>This is the line voltage and it should be a value
that is appropriate for your equipment. In the USA, it is typically
about 120 Volts while in Europe, it is about 220 Volts.</dd>
<dt><tt class="docutils literal">BATTV</tt></dt>
<dd>Unless you have additional battery packs, this
should be near 24 Volts plus or minus 5 Volts.</dd>
<dt><tt class="docutils literal">STATUS</tt></dt>
<dd>This is the status of the UPS and it should
normally be <tt class="docutils literal">ONLINE</tt>.</dd>
</dl>
<p>A very disturbing tendance is for some of the newer (Mar 2004) RS
and ES UPSes to have no Voltage information. This is an annoying bug,
but not serious. On the other hand, some of those UPSes now have no
battery charge information <tt class="docutils literal">BCHARGE</tt>. If <tt class="docutils literal">BCHARGE</tt> is zero in your
listing and you are running a Smart or a USB UPS, then you will
have to set the <tt class="docutils literal">BATTERYLEVEL</tt> directive in your apcupsd.conf file to
-1.</p>
<p>If you see a message to the effect of:</p>
<pre class="literal-block">
APCACCESS FATAL ERROR in apcaccess.c at line 336
tcp_open: cannot connect to server localhost on port 3551.
</pre>
<p>It means that you have probably not enabled the Network Information
Server in your configuration file for <tt class="docutils literal">apcaccess</tt> to work. This is
done by setting <tt class="docutils literal">NETSERVER</tt> and <tt class="docutils literal">NISPORT</tt> in your apcupsd.conf file
as shown above.</p>
</div>
<div class="section" id="communications-test">
<h3><a class="toc-backref" href="#id118">Communications Test</a></h3>
<p>At this point, you should ensure
that apcupsd is handling the connection to the UPS correctly. This
test assumes you have a UPS that speaks apcsmart protocol, over
either USB or a serial port. If you have an old-style
voltage-signaling UPS, please skip to the next section (<a class="reference internal" href="#simulated-power-fail-test">Simulated
Power Fail Test</a>).</p>
<p>When apcupsd detects a problem, it generates an EVENT, which
consists of sending a message to the system log then invoking the
<tt class="docutils literal">apccontrol</tt> script (normally in /etc/acpupsd/apccontrol) to handle
the event.</p>
<p>In order to create an event, remove the serial port plug from the
back of your computer or from the back of the UPS. Within 6
seconds, apcupsd should detect the lack of serial port
communications and broadcast a <tt class="docutils literal">wall</tt> message indicating that the
serial port communications was lost:</p>
<pre class="literal-block">
Warning communications lost with UPS lost.
</pre>
<p>At the same time, it sends the same message to the system log and
to the temporary EVENTS file (<tt class="docutils literal">/etc/apcupsd/apcupsd.events</tt>).</p>
<p>Plug the serial port plug back into your computer, and within about
12 seconds, apcupsd should reestablish communications and broadcast
and log the following message:</p>
<pre class="literal-block">
Communications with UPS restored.
</pre>
<p>If these messages are logged but not broadcast, either you have
your <tt class="docutils literal">mesg</tt> permission set to <tt class="docutils literal">no</tt> (see '<tt class="docutils literal">man wall</tt>' or '<tt class="docutils literal">man mesg</tt>'),
or there is a problem with apccontrol. If you are running a window
manager such as GNOME and don't have a console window open, you may
not receive the <tt class="docutils literal">wall</tt> messages. However, you should find them in
your system log file (normally <tt class="docutils literal">/var/log/messages</tt>) and in the
temporary EVENTS file, <tt class="docutils literal">/etc/apcupsd/apcupsd.events</tt>. For example, to
observe these events in the temporary EVENTS file, you might do a</p>
<pre class="literal-block">
tail -f /etc/apcupsd/apcupsd.events
</pre>
<p>Note, if you have installed from the RPM, the proper events file
may be <tt class="docutils literal">/var/log/apcupsd.events</tt>. You can find the actual filename by
checking your apcupsd.conf file before running the test.</p>
<p>If you do not observe these messages, you should correct this
problem before proceeding with additional tests.</p>
</div>
<div class="section" id="simulated-power-fail-test">
<h3><a class="toc-backref" href="#id119">Simulated Power Fail Test</a></h3>
<p>At this point, you should
verify that in the event of a power fail apcupsd properly calls
apccontrol. This test is appropriate for all models of UPSes (smart
or dumb).</p>
<p>To avoid the possibility that apcupsd might shut down your system,
locate where apccontrol resides on your system (normally,
/etc/apcupsd/apccontrol. Move this script to another location e.g.
apccontrol.save and replace it with the script found in
examples/safe.apccontrol. When that is done, ensure that your UPS
battery is fully charged and that you have at least 5 minutes of
remaining runtime on the batteries. This can be done by examining
the values of the <tt class="docutils literal">BATTCHG</tt> and <tt class="docutils literal">TIMELEFT</tt> variables in the
printout of '<tt class="docutils literal">apcaccess status</tt>'.</p>
<p>Athough this should not be necessary, as an extra precaution, you
can shutdown your machine, remove the plug from the UPS you are
testing, and plug your machine into another UPS or directly into
the wall. Doing so, will ensure that the UPS doesn't cut the power
to your machine at a bad time. Remember at the end of the testing
to plug your machine back into the UPS.</p>
<p>You can also minimize the risk from an unexpected shutdown by using
a journaling filesystem such as Linux's EXT3. All modern disk
drives park themselves safely when they power down, rather than
ploughing up oxide on your disk's recording surface. Thus,
unexpected power less has to hit very narrow timing windows in
order to trash an EXT3 transaction.</p>
<p>To begin the test, pull the power plug from the UPS. The first time
that you do this, psychologically it won't be easy, but after you
have pulled the plug a few times, you may even come to enjoy it. If
all goes well, apcupsd should detect the power failure and print
several warning messages. The first should appear after 5 to 6
seconds and read:</p>
<pre class="literal-block">
Warning power loss detected.
</pre>
<p>Then generally 6 seconds later, apcupsd is sure that it isn't a
transient effect, so it sends:</p>
<pre class="literal-block">
Power failure. Running on UPS batteries.
</pre>
<p>After a few more seconds (total around 15 seconds), plug the power
cord back in and ensure that apcupsd is aware that the power has
returned. It should print:</p>
<pre class="literal-block">
Power has returned...
</pre>
<p>If you do not observe the above messages, please correct the
situation before proceeding. The most likely cause of problems
are:</p>
<ul class="simple">
<li>apcupsd doesn't recognize the power failure because the
configuration directives are not correct. E.g. wrong cable.</li>
<li>The file <tt class="docutils literal">/etc/apcupsd/apccontrol</tt> doesn't exist or is not marked
as executable.</li>
</ul>
</div>
<div class="section" id="system-shutdown-test">
<h3><a class="toc-backref" href="#id120">System Shutdown Test</a></h3>
<p>This is an intermediate
test that you can do, for all UPS models before doing the Full
Power Down Test. First modify the <tt class="docutils literal">/etc/apcupsd/apccontrol</tt> file so
that in the <tt class="docutils literal">killpower</tt> case, the line that re-executes apcupsd
with the <tt class="docutils literal"><span class="pre">--killpower</span></tt> option is commented out. The original
line probably looks something like:</p>
<pre class="literal-block">
${APCUPSD} --killpower
</pre>
<p>when it is commented out, it looks like:</p>
<pre class="literal-block">
#${APCUPSD} --killpower
</pre>
<p>Now when you pull the power plug, and either the timer expires or
the batteries are exhausted (see the next section for more
details), the system should be fully shutdown.</p>
<p>After performing this test, please be sure to restore
<tt class="docutils literal">/etc/apcupsd/apccontrol</tt> to its previous state.</p>
</div>
<div class="section" id="full-power-down-test">
<h3><a class="toc-backref" href="#id121">Full Power Down Test</a></h3>
<p>To complete the testing, you should do a power fail shutdown of your
system. This test is applicable to all UPS models. Please do a
backup of your system or take other precautions before attempting
this to avoid the possibility of lost data due to a problem (I have
been through this at least 10 times and never once had problems,
but we all know that someday something will go wrong).</p>
<p>Before proceeding, please ensure that your halt script or the
equivalent has been properly updated by the install process to
contain the logic to call <tt class="docutils literal">apcupsd <span class="pre">--killpower</span></tt> or <tt class="docutils literal">apccontrol killpower</tt>
when it detects a power failure situation (the presence of a /etc/powerfail
file). See the <a class="reference internal" href="#building-and-installing-apcupsd">Building and Installing apcupsd</a> section of this manual,
or the README files for additional details about the halt modifications
necessary.</p>
<p>When you are ready to do the test, either simply pull the plug and
wait for the batteries to become exhausted, or set the <tt class="docutils literal">TIMEOUT</tt>
configuration directive to something like 60 so that the system
will shutdown before the batteries are exhausted. We recommend
doing the full shutdown without using <tt class="docutils literal">TIMEOUT</tt> to correctly
simulate a real power failure, but the choice is yours (I did it
once here, but now use <tt class="docutils literal">TIMEOUT 30</tt>).</p>
<p>If all goes well, your system should be shutdown before the
batteries are completely exhausted and the UPS should be powered
off by apcupsd. Please be aware that if you do the full power down,
you must ensure that your UPS is totally powered off. Otherwise, it
may have been given the command to power off, but due to a long
grace period it is still waiting. If you were to reboot your
computer during the grace period, the UPS could then suddenly turn
off the power (this happened to me). To avoid this problem, always
wait for your UPS to power itself off, or power if off manually
before restarting your computer. On my system, the UPS is
configured as at the factory to have a 180 second grace period
before shutting off the power. During this type of testing, 180
seconds <em>seems</em> like an eternity, so please take care to either
wait or manually power off your UPS. To determine what grace period
is programmed into your UPS EEPROM, run '<tt class="docutils literal">apcaccess eprom</tt>' and look
at the "Shutdown grace delay".</p>
<p>If you experienced so problems with
the above testing procedures, or if you are porting apcupsd to
another system, or you are simply curious, you may want to know
exactly what is going on during the shutdown process. If so, please
see the <a class="reference internal" href="#shutdown-sequence">Shutdown Sequence</a> section of this manual.</p>
</div>
<div class="section" id="apctest">
<h3><a class="toc-backref" href="#id122">apctest</a></h3>
<p><tt class="docutils literal">apctest</tt> is a program that allows you to talk
directly to your UPS and run certain low-level tests, adjust various settings
such as the battery installation date and alarm behavior, and perform a
battery runtime calibration. Here we describe how to use it for a SmartUPS
utilizing the apcsmart driver and RS232 serial connection.
The menus and options for USB, MODBUS, and simple signaling UPSes are different
but mostly self-explanatory.</p>
<p><em>Shutdown apcupsd if it is running.</em> This is important. Only one program can
communicate with the UPS at a time and if apcupsd is running, apctest will fail
to contact the UPS.</p>
<p>Run apctest by invoking it with no arguments.</p>
<p>It will read your installed apcupsd.conf configuration (so it knows
where to find the UPS) and then it will present you with the
following output:</p>
<pre class="literal-block">
2003-07-07 11:19:21 apctest 3.10.6 (07 July 2003) redhat
Checking configuration ...
Attached to driver: apcsmart
sharenet.type = DISABLE
cable.type = CUSTOM_SMART
You are using a SMART cable type, so I'm entering SMART test mode
mode.type = SMART
Setting up serial port ...
Creating serial port lock file ...
Hello, this is the apcupsd Cable Test program.
This part of apctest is for testing Smart UPSes.
Please select the function you want to perform.
1) Query the UPS for all known values
2) Perform a Battery Runtime Calibration
3) Abort Battery Calibration
4) Monitor Battery Calibration progress
5) Program EEPROM
6) Enter TTY mode communicating with UPS
7) Quit
Select function number: 1
</pre>
<p>Item 1 will probe the UPS for all values known to apcupsd and
present them in rather raw format. This output can be useful for
providing technical support if you are having problems with your
UPS.</p>
<p>Item 2 will perform a Battery Runtime Calibration. This test will
only be performed if your battery is 100% charged. Running the test
will cause the batteries to be discharged to approximately 30% of
capacity. The exact number depends on the UPS model. In any case,
apctest will abort the test if it detects that the battery charge
is 20% or less.</p>
<p>The advantage of doing this test is that the UPS will be able to
recalibrate the remaining runtime counter that it maintains in its
firmware. As your batteries age, they tend to hold less of a
charge, so the runtime calibration may not be accurate after
several years.</p>
<p>We recommend that perform a Battery Calibration about once a year.
You should not perform this calibration too often since discharging
the batteries tends to shorten their lifespan.</p>
<p>Item 3 can be used to abort a Battery Calibration in progress, if
you some how became disconnected.</p>
<p>Item 4 can be used to restart the monitoring of a Battery
Calibration if you should some how become disconnected during the
test.</p>
<p>Item 5 is used to program the EEPROM. Please see the <a class="reference internal" href="#configuration-directives-used-to-set-the-ups-eeprom">Configuration
Directives Used to Set the UPS EEPROM</a> chapter of this manual for the
details.</p>
<p>Item 6 will initiate a direct communication between your terminal
and the UPS, at which point you can enter raw UPS commands. Please
be aware that you should be careful what commands you enter because
you can cause your UPS to suddenly shutdown, or you can modify the
EEPROM in a way to disable your UPS. The details of the raw Smart
mode UPS commands can be found in the <a class="reference internal" href="#apc-smart-protocol">APC Smart Protocol</a>
chapter of this manual.</p>
<p>Item 7 will terminate apctest.</p>
</div>
</div>
<div class="section" id="monitoring-and-tuning-your-ups">
<h2><a class="toc-backref" href="#id123">Monitoring and Tuning your UPS</a></h2>
<p>After you have verified
that your UPS is working correctly, you will probably want to query
the state of its health occasionally. The tools apcupsd gives you
to do this include one command-line utility (apcaccess) and a GUI
you can use through a Web browser. You can also use apctest to tune
some parameters of the UPS itself.</p>
<div class="section" id="apcaccess">
<h3><a class="toc-backref" href="#id124">apcaccess</a></h3>
<p><tt class="docutils literal">apcaccess</tt> is a program (normally found in
<tt class="docutils literal">/sbin/apcaccess</tt>) that permits you to print out the complete status
of your UPS.</p>
<p>apcaccess will use the Network Information Server to obtain the
necessary information. You
can specify a second optional argument to apcaccess in the form of
<tt class="docutils literal">host:port</tt> where the <tt class="docutils literal">:port</tt> is optional. The default is
<tt class="docutils literal">localhost:3551</tt>. Please note that in versions prior to 3.10.6, the
default NIS port was 7000, so if you are mixing versions, you will
need to take a lot of care to ensure that all components are using
the same port.</p>
<p>To enable the apcupsd Network Information Server, which is normally
the default, you set:</p>
<pre class="literal-block">
NETSERVER on
NISPORT 3551
</pre>
<p>in your <tt class="docutils literal">apcupsd.conf</tt> file.</p>
<p>The full form of the apcaccess command is:</p>
<pre class="literal-block">
apcaccess status localhost:3551
</pre>
<p>where only apcaccess status should normally be needed. localhost
may be replaced by any machine name, fully qualified domain name,
or IP address, which means that apcaccess can access any UPS on the
network running the Network Information Server.</p>
<p>The <tt class="docutils literal">status</tt> command line option of apcaccess will produce a full
printout of all the STATUS variables used by apcupsd. This can
be very helpful for checking the condition of your UPS and to know
whether or not apcupsd is properly connected to it.</p>
<p>Please note that if you invoke apcaccess within the first 30
seconds of launching apcupsd, you will likely get an error message
such as:</p>
<pre class="literal-block">
APCACCESS FATAL ERROR in apcaccess.c at line 336
tcp_open: cannot connect to server localhost on port 3551.
</pre>
<p>This is because apcupsd is still in the process of initializing the
UPS. The solution is to wait at least 30 seconds after starting apcupsd
before launching apcaccess.</p>
<p>For a SmartUPS 1000 apcaccess will emit the following output:</p>
<pre class="literal-block">
DATE : Fri Dec 03 12:34:26 CET 1999
HOSTNAME : matou
RELEASE : 3.7.0-beta-1
CABLE : Custom Cable Smart
MODEL : SMART-UPS 1000
UPSMODE : Stand Alone
UPSNAME : UPS_IDEN
LINEV : 232.7 Volts
MAXLINEV : 236.6 Volts
MINLINEV : 231.4 Volts
LINEFREQ : 50.0 Hz
OUTPUTV : 232.7 Volts
LOADPCT : 11.4 Percent Load Capacity
BATTV : 27.7 Volts
BCHARGE : 100.0 Percent
MBATTCHG : 5 Percent
TIMELEFT : 112.0 Minutes
MINTIMEL : 3 Minutes
SENSE : Low
DWAKE : 060 Seconds
DSHUTD : 180 Seconds
LOTRANS : 204.0 Volts
HITRANS : 253.0 Volts
RETPCT : 050.0 Percent
STATFLAG : 0x08 Status Flag
STATUS : ONLINE
ITEMP : 29.2 C Internal
ALARMDEL : Low Battery
LASTXFER : U command or Self Test
SELFTEST : NO
STESTI : 336
DLOWBATT : 02 Minutes
DIPSW : 0x00 Dip Switch
REG1 : 0x00 Register 1
REG2 : 0x00 Register 2
REG3 : 0x00 Register 3
MANDATE : 01/05/99
SERIALNO : GS9902009459
BATTDATE : 01/05/99
NOMOUTV : 230.0
NOMBATTV : 24.0
HUMIDITY : N/A
AMBTEMP : N/A
EXTBATTS : 0
BADBATTS : N/A
FIRMWARE : 60.11.I
APCMODEL : IWI
END APC : Fri Dec 03 12:34:33 CET 1999
</pre>
<p>For the various smaller, cheaper APC USB UPSes, such as the CS, ES,
..., you will get much of the information that is presented above,
but not all of it. For example, you will not get <tt class="docutils literal">MAXLINEV</tt>,
<tt class="docutils literal">MINLINEV</tt>, <tt class="docutils literal">LINEFREQ</tt>, ... and in particular, the LOADPCT will be zero
when you are running on mains. <tt class="docutils literal">LOADPCT</tt> will display when the UPS is
on batteries. You must remember that the non-SmartUPSes are much
simpler (and less expensive) and therefore produce less
information.</p>
</div>
<div class="section" id="apcupsd-notification-and-events">
<h3><a class="toc-backref" href="#id125">Apcupsd Notification and Events</a></h3>
<p>When a major event is
generated within apcupsd, control is passed to the script
apccontrol normally found in /etc/apcupsd/apccontrol. The event
name, and a number of other important parameters are passed to the
script.</p>
<p>The major function of the apccontrol script is to perform a
shutdown of the system (as well as the killpower operation). In
addition, another major task for this script is to notify you by
email when certain events such as powerfail occur.</p>
<p>Since apccontrol is a script, you can customize it to your own
needs using any text editor. To do so, you must have a minimal
knowledge of Unix shell programming. In addition, another feature
is that you can write your own scripts that will be automatically
called by apccontrol before any of its own code is executed.
Details of the events and how to program them are contained in the
Advanced topics section entitled <a class="reference internal" href="#customizing-event-handling">Customizing Event Handling</a>.</p>
</div>
<div class="section" id="apcupsd-network-monitoring-cgi-programs">
<h3><a class="toc-backref" href="#id126">apcupsd Network Monitoring (CGI) Programs</a></h3>
<p>There are four CGI programs (multimon.cgi, upsstats.cgi, upsfstats.cgi, and
upsimage.cgi). To have them properly installed, you must run the
'<tt class="docutils literal">./configure</tt>' command with <tt class="docutils literal"><span class="pre">--enable-cgi</span></tt> and you should
specify an installation directory with <tt class="docutils literal"><span class="pre">--with-cgi-bin=</span></tt> or
load them manually. The default directory for installation of the
CGI programs is <tt class="docutils literal">/etc/apcupsd</tt>, which is not really where you want
them if you are going to use them. Normally, they should go in the
cgi-bin of your Web server.</p>
<p>Once built and loaded, they will give you the status of your UPS or
UPSes via a web browser.</p>
<p>Normally only <tt class="docutils literal">multimon.cgi</tt> is directly invoked by the user.
However, it is possible to directly invoke <tt class="docutils literal">upsstats.cgi</tt> and
<tt class="docutils literal">upsfstats.cgi</tt>. <tt class="docutils literal">upsimage.cgi</tt> should never be directly invoked as it
is used by <tt class="docutils literal">upsstats.cgi</tt> to produce the bar charts.</p>
<div class="section" id="setting-up-and-testing-the-cgi-programs">
<h4><a class="toc-backref" href="#id127">Setting up and Testing the CGI Programs</a></h4>
<p>Before using multimon and the other CGI programs, first ensure that
apcupsd is configured to run the Network Information Server. This
is done by setting <tt class="docutils literal">NETSERVER on</tt> in /etc/apcupsd/apcupsd.conf.
This switch is on by default.</p>
<p>Next you must edit the hosts file /etc/apcupsd/hosts.conf and at
the end, add the name of the hosts you want to monitor and a label
string for them. For example:</p>
<pre class="literal-block">
MONITOR matou "Server"
MONITOR polymatou "Backup server"
MONITOR deuter "Disk server"
</pre>
<p>matou, polymatou, and deuter are the network names of the three
machines currently running apcupsd. Please note that the network
names may either be IP addresses or fully qualified domain names.
The network name (or IP address) may optionally be followed by
<tt class="docutils literal">:port</tt>, where the port is the NIS port address you wish to use.
This is useful if you are running multiple copies of apcupsd on the
same system or if you are running in a mixed vendor environment
where the NIS port assignments differ. An example could be the
following:</p>
<pre class="literal-block">
MONITOR matou "Server"
MONITOR polymatou "Backup server"
MONITOR deuter "Disk server"
MONITOR polymatou:7001 "APC USB UPS"
</pre>
<p>where the USB copy of apcupsd has been configured to use port 7001 by
modifying apcupsd.conf. Note, the default NIS port is 3551 on most
platforms.</p>
<p>To test multimon.cgi, you can execute it as non-root directly from
the source cgi build directory. To do so, enter at a shell prompt:</p>
<pre class="literal-block">
./multimon.cgi
</pre>
<p>If everything is set up correctly, it will print a bunch of HTML
with the values of the machines that you have put in the hosts.conf
file. It should look something like the following (note, only a
small portion of the output is reproduced here):</p>
<pre class="literal-block">
Content-type: text/html
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN"
"http://www.w3.org/TR/REC-html40/loose.dtd">
<HTML>
<HEAD><TITLE>Multimon: UPS Status Page</TITLE></HEAD>
<BODY BGCOLOR="#FFFFFF">
<TABLE BGCOLOR="#50A0A0" ALIGN=CENTER>
<TR><TD>
<TABLE CELLPADDING=5>
<TR>
<TH COLSPAN=10 BGCOLOR="#60B0B0">
<FONT SIZE="+2">APCUPSD UPS Network Monitor</FONT>
<BR>Sun Jan 16 12:07:27 CET 2000</TH>
</TR>
<TR BGCOLOR="#60B0B0">
<TH COLSPAN=1>System</TH>
<TH COLSPAN=1>Model</TH>
<TH COLSPAN=1>Status</TH>
...
</pre>
<p>If you do not get similar output, check the permissions of the
/etc/apcupsd directory and of those of /etc/apcupsd/hosts.conf to
ensure that your web server can access it. At many sites, the Apache
server is not running as root, so you must be
careful to ensure that that /etc/apcupsd/hosts.conf and
/etc/apcupsd/multimon.conf are world readable.</p>
<p>To invoke multimon in your Web browser, enter:</p>
<p><tt class="docutils literal"><span class="pre">http://your-site/cgi-bin/multimon.cgi</span></tt></p>
<p>You should get something similar to the screen shot shown below.</p>
<p>If you wish additional control over the colors, type faces, and
sizes of the multimon output, you may simply edit the apcupsd.css
file to specify the styles you prefer.</p>
</div>
<div class="section" id="using-the-cgi-programs-on-windows">
<h4><a class="toc-backref" href="#id128">Using the CGI Programs on Windows</a></h4>
<p>The CGI programs compiled for Windows are included in the Windows package
starting with apcupsd-3.14.7.</p>
<p>The CGI programs included with the Windows package are intended
to be run on Windows. If your web server is running on Linux or another
operating system, you will need to obtain binary packages for that platform
(or build them from source) instead. The windows build of the CGI programs has
been tested with the Apache web server for Win32. They should also work with MS
Internet Information Server (IIS).</p>
<p>To use the programs, copy the contents of the <tt class="docutils literal">cgi/</tt> directory from your
apcupsd installation directory to the <tt class="docutils literal"><span class="pre">cgi-bin/</span></tt> directory of your web server.
Consult your web server's documentation for how to enable CGI programs to be
executed. Sometimes special security settings are required.</p>
<p>Configure the hosts.conf file as described above. The programs expect to find
the <tt class="docutils literal">hosts.conf</tt> file and the <tt class="docutils literal">apcupsd.css</tt> file in the directory
<tt class="docutils literal">\apcupsd\etc\apcupsd</tt> on the same drive letter as the web server's
<tt class="docutils literal"><span class="pre">cgi-bin</span></tt> directory. If you installed apcupsd into <tt class="docutils literal"><span class="pre">C:\apcupsd</span></tt> (the
default) and your web server's <tt class="docutils literal"><span class="pre">cgi-bin/</span></tt> directory is also located on the
<tt class="docutils literal">C:</tt> drive, no further changes are necessary. If you installed apcupsd into a
different directory or your web server <tt class="docutils literal"><span class="pre">cgi-bin</span></tt> is on another drive, you will
need to relocate <tt class="docutils literal">hosts.conf</tt> and <tt class="docutils literal">apcupsd.css</tt> from the apcupsd install
location to <tt class="docutils literal">\apcupsd\etc\apcupsd</tt> on the appropriate drive.</p>
</div>
<div class="section" id="multimon-cgi">
<h4><a class="toc-backref" href="#id129">multimon.cgi</a></h4>
<p>This program
monitors multiple UPSes at the same time. A typical output of
multimon.cgi as displayed in your Web browser might look like the
following:</p>
<div align="center" class="align-center"><img alt="./multimon.png" class="align-center" src="./multimon.png" /></div>
<p>The machines monitored as well as the values and their column
headings are all configurable (see /etc/apcupsd/hosts.conf and
/etc/apcupsd/multimon.conf)</p>
</div>
<div class="section" id="upsstats-cgi">
<h4><a class="toc-backref" href="#id130">upsstats.cgi</a></h4>
<p>By clicking on the <tt class="docutils literal">system</tt> name in the multimon.cgi display, you will
invoke upsstats.cgi for the specified system, which will produce a bar
graph display of three of the monitored values. For example,</p>
<div align="center" class="align-center"><img alt="./status.png" class="align-center" src="./status.png" /></div>
<p>You can display different bar graphs by selecting different
variables from the drop down menus at the top of each of the three
bar graphs.</p>
<p>As with multimon, if you have your local host configured in the
/etc/apcupsd/hosts.conf file, you can execute it from a Unix shell
from the source cgi directory as follows:</p>
<pre class="literal-block">
./upsstats.cgi
</pre>
<p>As with multimon, quite a few lines of html should then be displayed.</p>
</div>
<div class="section" id="upsfstatus-cgi">
<h4><a class="toc-backref" href="#id131">upsfstatus.cgi</a></h4>
<p>If you
would like to see all of the STATUS variables available over the
network, click on the <tt class="docutils literal">Data</tt> field of the desired system, and your
browser will display something like the following:</p>
<pre class="literal-block">
APC : 001,048,1109
DATE : Thu Dec 02 17:27:21 CET 1999
HOSTNAME : matou.sibbald.com
RELEASE : 3.7.0-beta-1
CABLE : Custom Cable Smart
MODEL : SMART-UPS 1000
UPSMODE : Stand Alone
UPSNAME : UPS_IDEN
LINEV : 223.6 Volts
MAXLINEV : 224.9 Volts
MINLINEV : 222.3 Volts
LINEFREQ : 50.0 Hz
OUTPUTV : 223.6 Volts
LOADPCT : 6.2 Percent Load Capacity
BATTV : 27.9 Volts
BCHARGE : 100.0 Percent
MBATTCHG : 5 Percent
TIMELEFT : 167.0 Minutes
MINTIMEL : 3 Minutes
SENSE : High
DWAKE : 060 Seconds
DSHUTD : 020 Seconds
LOTRANS : 196.0 Volts
HITRANS : 253.0 Volts
RETPCT : 050.0 Percent
STATFLAG : 0x08 Status Flag
STATUS : ONLINE
ITEMP : 35.1 C Internal
ALARMDEL : Low Battery
LASTXFER : U command or Self Test
SELFTEST : NO
STESTI : 336
DLOWBATT : 02 Minutes
DIPSW : 0x00 Dip Switch
REG1 : 0x00 Register 1
REG2 : 0x00 Register 2
REG3 : 0x00 Register 3
MANDATE : 01/11/99
SERIALNO : GS9903001147
BATTDATE : 01/11/99
NOMOUTV : 230.0
NOMBATTV : 24.0
HUMIDITY : N/A
AMBTEMP : N/A
EXTBATTS : 0
BADBATTS : N/A
FIRMWARE : 60.11.I
APCMODEL : IWI
END APC : Thu Dec 02 17:27:25 CET 1999
</pre>
<p>You should get pretty much the same output mixed in with html if
you execute upsfstats.cgi directly from a Unix shell in the cgi
subdirectory as explained above for upsstats.cgi and multimon.cgi.</p>
</div>
<div class="section" id="a-tip-from-carl-erhorn-for-sun-systems">
<h4><a class="toc-backref" href="#id132">A Tip from Carl Erhorn for Sun Systems:</a></h4>
<p>It is possible to run the CGI code to monitor your
UPS using the answerbook HTTP server that runs on Solaris. As long
as your server has the Answerbook2 web server installed and
running, you can insert the cgi scripts into the cgi directory of
the web server, and access the cgi using something like:</p>
<p><tt class="docutils literal"><span class="pre">http://hostname:8888/cgi/multimon.cgi</span></tt></p>
</div>
<div class="section" id="cgi-credits">
<h4><a class="toc-backref" href="#id133">CGI Credits</a></h4>
<p>Many thanks go to Russell Kroll <a class="reference external" href="mailto:rkroll@exploits.org">rkroll@exploits.org</a> who wrote
the CGI programs to work with his UPS Monitoring system named
Network UPS Tools (NUT). Thanks also to Jonathan Benson
<a class="reference external" href="mailto:jbenson@technologist.com">jbenson@technologist.com</a> for initially
adapting the upsstatus.cgi program to work with apcupsd.</p>
<p>We have enhanced the bar graph program and hope that our changes
can be useful to the original author in his project.</p>
</div>
</div>
<div class="section" id="security-issues">
<h3><a class="toc-backref" href="#id134">Security Issues:</a></h3>
<ul class="simple">
<li><tt class="docutils literal">apcupsd</tt> runs as root.</li>
<li>If you have <tt class="docutils literal">NETSERVER ON</tt> in your apcupsd.conf file (which is
the default), be aware that anyone on the network can read the
status of your UPS. This may or may not pose a problem. If you
don't consider this information privileged, as is the case for
many, there is little risk. In addition, if you have a perimeter
firewall or NATting router with typical settings only users on your
local network access to your UPS information. You may also restrict
access using using firewall settings (see below) or TCP Wrappers
(see below).</li>
</ul>
<div class="section" id="firewall-settings">
<h4><a class="toc-backref" href="#id135">Firewall Settings</a></h4>
<p>If you are running apcupsd as an NIS server, you will need to
ensure that the clients can reach it by opening up <tt class="docutils literal">NISPORT</tt>
(default: TCP 3551) on any firewall running on the server. You may
wish to configure your firewall(s) to <em>only</em> allow connections from
your local network or specifically from the masters, slaves, and
servers as needed.</p>
</div>
<div class="section" id="tcp-wrappers">
<h4><a class="toc-backref" href="#id136">TCP Wrappers</a></h4>
<p>If your operating system does not support a host based firewall (a
firewall running on the local machine) then you may try to get some
of the functionality of such a firewall with TCP Wrappers. As of
apcupsd version 3.8.2, TCP Wrappers are implemented if you turn
them on when configuring <tt class="docutils literal">./configure <span class="pre">--with-libwrap</span></tt>. With
this code enabled, you may control who may access your apcupsd via
TCP connections (the Network Information Server). This control is
done by modifying the file: /etc/hosts.allow. This code is
implemented but untested. If you use it, please send us some
feedback.</p>
</div>
</div>
<div class="section" id="configuring-your-eeprom">
<h3><a class="toc-backref" href="#id137">Configuring Your EEPROM</a></h3>
<p>If you have a SmartUPS, there
are depending on the UPS at least 12 different values stored in the
EEPROM that determine how the UPS reacts to various conditions such
as high line voltage, low line voltage, power down grace periods,
etc.</p>
<p>In general, for the moment, we do not recommend that you change
your EEPROM values unless absolutely necessary. There have been
several reported cases of problems setting the Low Transfer
Voltage. Consequently, if at all possible, do not attempt to change
this value.</p>
<div class="section" id="using-apctest-to-configure-your-eeprom">
<h4><a class="toc-backref" href="#id138">Using apctest to Configure Your EEPROM</a></h4>
<p><em>To make the EEPROM changes with apctest you must first stop the
apcupsd daemon.</em> After apcupsd is stopped you may invoke apctest (as root).</p>
<p>We recommend that you change the EEPROM as little as is absolutely
necessary since it is a somewhat delicate process that has
occasionally produced problems (i.e. improper EEPROM values are
displayed after the update).</p>
<p>apctest will present a menu of options which are generally self-explanatory.
Note that USB connections will show a difference set of options than
smart serial connections.</p>
</div>
</div>
</div>
<div class="section" id="maintaining-your-ups-batteries">
<h2><a class="toc-backref" href="#id139">Maintaining Your UPS Batteries</a></h2>
<div class="section" id="battery-technology">
<h3><a class="toc-backref" href="#id140">Battery Technology</a></h3>
<p>Sealed Lead Acid (SLA) batteries, otherwise known as Valve Regulated Lead Acid
(VRLA) batteries, were originally known as "dry batteries". When first
introduced in the 1950s, they used a gel electrolyte. The otherwise free acid
was immobilised with a fine silica powder and formed a gel substance.</p>
<p>In the 1970s the technology moved to Absorbed Glass Mat (AGM) where the
separators between the lead plates are made of highly porous micro-fine glass
fibres which absorb and immobilise the acid and prevent it from spilling. A
crack or hole in the casing of a VRLA battery using AGM technology will not
result in a measurable electrolyte spill. Spill containment with VRLA batteries
is therefore not meaningful or appropriate.</p>
<p>AGM has became the preferred VRLA technology for use in standby or float
applications and is used in UPSes in the telecommunications, power, and many
other mission critical industries where the power supply must not be
interrupted. APC UPSes use VRLA batteries. VRLA batteries are designed to
recombine hydrogen and oxygen and emit only extremely small amounts of
hydrogen under normal operating conditions. Normal room ventilation is
sufficient to remove any hydrogen, so special ventilation is not required.</p>
</div>
<div class="section" id="battery-life">
<h3><a class="toc-backref" href="#id141">Battery Life</a></h3>
<p>Most brand name UPS batteries should last 3-5 years. Some APC Back-UPS models
may have a shorter battery life expectancy. Refer to the user's manual of your
APC Back-UPS to determine the exact battery life expectancy or contact APC
Technical Support.</p>
<p>Below are some APC guidelines for ensuring optimum battery life expectancy:</p>
<ol class="arabic simple">
<li>Make sure that you keep your APC UPS in a cool, dry location with plenty of ventilation. Ideally, the temperature where your UPS is kept should not exceed 75 Deg F (24 Deg C). Also, for ventilation purposes, leave roughly one to two inches on each side for proper airflow.</li>
<li>The optimum operating temperature for a lead acid battery is 25 Deg C (77 Deg F). Elevated temperature reduces longevity. As a guideline, every 8 Deg C (15 Deg F) rise in temperature will cut the battery life in half. A battery which would last for 6 years at 25 Deg C (77 Deg F), will only be good for 3 years if operated at 33 Deg C (95 Deg F). Keep in mind that the battery temperature inside your UPS will always be warmer than the ambient temperature of the location where the UPS is installed.</li>
<li>Only perform runtime calibrations on your UPS one or two times a year, if necessary. Some of our customers want to check their systems to verify that their runtime is sufficient. However, consistently performing these calibrations can significantly decrease the life expectancy of your battery.</li>
<li>Do not store batteries for extended periods of time. New batteries can be stored for 6 to 12 months from date of purchase. After this period, the battery should be used or it will lose a great deal of its charge. It is not advisable to store batteries that have already been in use.</li>
<li>Do not exceed 80 percent of a UPS unit's rated capacity due to the reduction in run time. When you increase your load, your runtime decreases. In the event of a utility power failure, a UPS loaded to full capacity will drain and discharge it's battery quickly and will decrease the life expectancy.</li>
</ol>
<p>The Smart-UPS detects line voltage distortions such as spikes, notches, dips,
and swells, as well as distortions caused by operation with inexpensive
fuel-powered generators. By default, the UPS reacts to distortions by
transferring to on-battery operation to protect the equipment that you are
plugging into the UPS. Where power quality is poor, the UPS may frequently
transfer to on-battery operation. Battery longevity and service life of the
UPS may be conserved by reducing the sensitivity of the UPS, as long as your
equipment can operate normally under the conditions detailed below. Any type
of voltage disturbance includes; High/Low/No RMS Voltage, Total Harmonic
Distortion(THD), Change in Voltage over Time(dv/dt), Frequency (Hz) out of
tolerance.</p>
<dl class="docutils">
<dt><strong>High Sensitivity Mode</strong></dt>
<dd>In the event of any type of voltage disturbance, the UPS will transfer to
battery power and watch the AC line until it can transfer back to line. The
transfer time in this mode depends on how far the line voltage deviates from
the sinewave reference.</dd>
<dt><strong>Medium Sensitivity Mode</strong></dt>
<dd>In the event of a RMS voltage-out-of-tolerance(High/Low/No) and
RMS-rate-of-change disturbances(dv/dt) in the line voltage, the UPS will
transfer to battery power and watch the AC line until it can transfer back to
line. In this mode the transfer times are longer but still within acceptable
limits to insure the continuity of a computer's operation.</dd>
<dt><strong>Low Sensitivity Mode</strong></dt>
<dd>In the event of a RMS voltage-out-of-tolerance disturbances(High/Low/No)
in the line voltage, the UPS will transfer to battery power and watch the
AC line until it can transfer back to line. In this mode the transfer times
are longer but still within acceptable limits to insure the continuity of a
computer's operation.</dd>
</dl>
<p>To change the sensitivity of the UPS, press the small, white "sensitivity"
button on the rear of the UPS. Use a pointed object (such as a pen) to do so.
The default setting is "high"; press the button once to set the sensitivity to
"medium", and press it again to set it to "low"; pressing it a third time will
set it back to "high". The sensitivity setting change will take effect
immediately. The green LED next to the button is a sensitivity setting
indicator - brightly lit is "high" sensitivity, dimly lit is "medium", and
off is "low" sensitivity.</p>
</div>
<div class="section" id="flashing-battery-charge-graph-leds">
<h3><a class="toc-backref" href="#id142">Flashing Battery Charge Graph LEDs</a></h3>
<p>The battery charge graph LEDs on the front panel of a Smart-UPS will flash
in unison when the UPS is operating online and the runtime remaining
(calculated by the Smart-UPS microprocessor) is less than two minutes
more than the low battery signal warning time (minimum of two minutes).</p>
<p>This would usually indicate that you need to either decrease the load
or install new batteries. If the batteries are new, then you need to perform
a runtime calibration (see below).</p>
<p>At a pinch, you could also decrease the low battery warning time. There are
four possible settings: 2, 5, 7, or 10 minutes.</p>
</div>
<div class="section" id="battery-replacement">
<h3><a class="toc-backref" href="#id143">Battery Replacement</a></h3>
<p>If you own your UPS for long enough, you will inevitably need to replace
the UPS battery or battery cartridge. An APC battery cartridge comprises
two batteries physically stuck together with double-sided tape and wired
in series.</p>
<p>After the decision to replace the batteries, you will face
another decision almost immediately: whether to purchase genuine APC
replacement batteries or not. There are pros and cons to purchasing
genuine replacement APC batteries.</p>
<p><strong>APC Battery Pros</strong></p>
<ul class="simple">
<li>APC batteries are supported by APC</li>
<li>APC batteries come with all the necessary hardware</li>
<li>APC batteries come as pre-made cartridges</li>
<li>APC batteries will physically fit your UPS</li>
</ul>
<p><strong>APC Battery Cons</strong></p>
<ul class="simple">
<li>APC batteries cost up to 4 times the cost of third party batteries</li>
</ul>
<p>There are also pros and cons to purchasing third party batteries.</p>
<p><strong>Third Party Battery Pros</strong></p>
<ul class="simple">
<li>A third party battery may cost up to 1/4 the price of APC batteries</li>
<li>A third party battery may have a higher capacity for the same physical size</li>
</ul>
<p><strong>Third Party Battery Cons</strong></p>
<ul class="simple">
<li>You will need to recycle your battery hardware (cables, connectors etc)</li>
<li>You will need to create your own battery cartridges (with double-sided tape)</li>
<li>You will need to ensure the third party battery is the right physical size</li>
<li>You will need to ensure the third party battery is the right capacity</li>
<li>Use of a third party battery will void APC's Equipment Protection Policy</li>
<li>Use of a third party battery may void UL, CSA, VDE, and other safety certifications (according to APC)</li>
</ul>
<p>If you do decide to use third party replacement batteries, please do not
choose the cheapest available generic SLA batteries. These batteries will,
almost without exception, not last as long as brand name
batteries and will need replacing within 12-18 months instead of 3-5 years.
Even when using brand name replacement batteries, make sure that you choose
the UPS version (aka "standby") which may cost slightly more,
but which will last significantly longer in typical UPS usage (long periods
of standby punctuated with infrequent deep discharges).</p>
<p>The brands of battery found in genuine APC battery cartridges have included:
Panasonic and B&B Battery (aka Best & Best Battery and BB Battery). Yuasa
(aka Genesis) is also a recommended brand, albeit a bit on the pricey side.</p>
<p><strong>Note:</strong> When substituting a third party battery with a higher capacity than
the original, make sure that it still physically fits in the UPS casing. If the
battery does not fit, do not be tempted to install it "externally". The UPS
may not be able to charge it in a timely manner and/or it may damage the UPS
charging circuitry without appropriate modifications which are generally
beyond an end user's capability.</p>
</div>
<div class="section" id="battery-installation">
<h3><a class="toc-backref" href="#id144">Battery Installation</a></h3>
<p>Although you can do a hot swap of your batteries while the computer and
any other connected equipment is running, it may not be very satisfactory
because the UPS will not always detect that the batteries have been swapped
and apcupsd will continue to report "Low Battery".</p>
<p>There are several ways to correct this situation:</p>
<p>1. If you have a "smart" UPS model, you can force a self-test to make the
UPS notice that the battery has been replaced.</p>
<p>2. If after a self-test, the UPS does not detect that the battery has been
replaced, you can use apctest to do a soft battery runtime calibration.
For details of doing this, refer to the "Soft" Runtime Calibration section
below.</p>
<p>3. If after the soft battery runtime recalibration, the UPS does not detect
that the battery has been replaced, you will need to do a manual battery
runtime calibration. For details of doing this, refer to the "Manual" Runtime
Calibration section below.</p>
</div>
<div class="section" id="soft-runtime-calibration">
<h3><a class="toc-backref" href="#id145">"Soft" Runtime Calibration</a></h3>
<p>A runtime calibration causes the UPS to recalculate its available runtime
capacity based on its current load.</p>
<p>Caution: a runtime calibration will deeply discharge the UPS batteries, which
can leave a UPS temporarily unable to support its equipment if a utility power
failure occurs. Frequent calibrations reduce the life of batteries. APC
recommends performing a runtime calibration only annually, semiannually, or
whenever the load on the UPS is increased.</p>
<p>In order to perform a "soft" runtime calibration it is necessary to wait for
the UPS to recharge its batteries to 100% capacity. Once this has been done,
you can then initiate a runtime calibration through apctest.</p>
<p>APC Documentation Notes:</p>
<p>1. In order for the calibration to be accurate, the output load has to be more
than 40% (some APC documentation recommends at least 30%). Also, it
is advisable not to increase or reduce the load when the UPS is calibrating
its run time.</p>
<p>2. Under no circumstances should the UPS be turned off during a run time
calibration procedure! Once initiated, the calibration must be allowed to run
until completion.</p>
<p>3. The run time calibration procedure is not necessary nor advisable for a new
UPS. Only old UPSes with batteries that are not subject to discharge for long
periods of time should be allowed to perform a run time calibration.</p>
<p>4. Matrix-UPS and Smart-UPS recalculate the runtime-related parameters every
time the UPS goes on battery.</p>
<p>When doing a runtime calibration with "older" batteries, APC Technical Support
recommend doing a complete discharge and recharge first.</p>
<p>If you have "dumb" UPS (aka simple signalling) like a Back-UPS, then your only
option is to do a manual runtime calibration.</p>
</div>
<div class="section" id="manual-runtime-calibration">
<h3><a class="toc-backref" href="#id146">"Manual" Runtime Calibration</a></h3>
<p>Most of the information in this section is taken from APC's website.
Any non-APC additions have been inserted in square brackets.</p>
<p>For a "smart" or "smart signalling" Back-UPS Pro or Smart-UPS:</p>
<blockquote>
<p>Perform a Runtime Calibration. This is a manual procedure and
should not be confused with the runtime calibration performed
through PowerChute plus [or apctest]. The batteries inside of the
Smart-UPS are controlled by a microprocessor within the UPS.
Sometimes it is necessary to reset this microprocessor, especially
after the installation of new batteries. Stop the PowerChute plus
[or apcupsd] software from running and disconnect the serial cable.
There must be at least a 30% load attached to the UPS during this
procedure, but the process will cause the UPS to shut off and cut
power to its outlets. Therefore, attach a non-critical load to the
UPS and then force the UPS on battery by disconnecting it from
utility power [suggest not disconnecting, but simply turning off
utility power thereby preserving earthing]. Allow the unit to
run on battery until it turns off completely. Make sure a 30% load
is present! Plug the UPS back into the wall outlet [switch utility
power back on] and allow it to recharge (it will recharge more quickly
turned off and with no load present). Once the unit has recharged,
the "runtime remaining" calculation should be more accurate.
Remember that if the unit is an older model, then the runtime will
not improve significantly.</p>
<p>Background:</p>
<p>An APC Smart-UPS has a microprocessor which calculates runtime
primarily based on the load attached to the UPS and on its battery
capacity. On the right side of the front display panel there is a
vertical graph of five LEDs. Each LED is an indication of battery
charge in increments of twenty percent: 20, 40, 60, 80, 100%
(bottom to top). For example, if the battery charge is 99%, then
only four of the five LEDs are illuminated.</p>
<p>To ensure that an operating system receives a graceful shutdown
when using PowerChute plus or a SmartSlot accessory, an alert is
generated by the Smart-UPS indicating that the UPS has reached a
low battery condition. The alert is audible (rapid beeping), visual
(flashing battery LED or LEDs), and readable through the graphical
interface of PowerChute plus software (or a native UPS shutdown
program within a particular operating system.) In order to
calculate this "low battery condition," all Smart-UPS products have
a preconfigured low battery signal warning time of two minutes
(this is the factory default setting). There are a total of four
user-changeable settings: 2, 5, 7, or 10 minutes. If the low
battery signal warning time is set for 2 minutes, then the alerts
will activate simultaneously two minutes prior to shutdown.
Similarly, if the total runtime for a particular UPS is 30 minutes
with a low battery signal warning time set at 10 minutes, then the
UPS will run on battery for 20 minutes before the low battery alert
begins.</p>
<p>Total runtime is primarily based on two factors, battery capacity
and UPS load. UPS load and runtime on battery are inversely
proportional: as load increases, battery runtime decreases and vice
versa. When utility power is lost, the UPS begins discharging the
battery in order to support the attached load. Once power returns,
the Smart-UPS will automatically begin to recharge its battery.</p>
</blockquote>
<p>For a Matrix UPS:</p>
<blockquote>
<p>It is unnecessary to subject a battery bank to an excessively long
calibration. Remove battery packs or increase the load (space heaters
are good dummy loads) to obtain a reasonable time length for the
calibration (under an hour if possible).</p>
<p>At the start of a calibration, the Matrix microprocessor saves the
Estimated Run Time displayed.</p>
<p>The unit will then go to battery power until the capacity is 25%. After
this run time has been completed, the original Estimated Run Time is compared
with the actual run time. It will then increase or decrease this value to
correspond to the new run time achieved. If, at any time during the discharge,
one of the following rules is violated the calibration will be aborted or
corrupted:</p>
<ol class="arabic simple">
<li>Battery capacity must be 100% at start of calibration (all packs must indicated as float).</li>
<li>Initial "Estimated Run Time" must not exceed 128 minutes (remove battery packs if necessary).</li>
<li>Load must be above 25%.</li>
<li>Load must not fluctuate more than ± 5%.</li>
<li>The UPS must be allowed to run down to 25% battery capacity. PowerChute [or apcupsd] and Accessories must be removed since they can abort the calibration prematurely.</li>
</ol>
</blockquote>
<p>For a "dumb" or "simple signalling" UPS (eg a Back-UPS):</p>
<blockquote>
This could be done if you have changed your equipment load or battery.
Stop the PowerChute [or apcupsd] software from running; disconnect the
serial cable between the computer and UPS. Next unplug the UPS from the
wall [suggest not disconnecting but simply turning off the utility power
thereby preserving the earthing] and let it run on battery until it
reaches low battery. Once it reaches low battery plug it back into
the wall outlet [turn the utility power back on] and let it recharge.
Recharge time can take up to 4 hours.</blockquote>
</div>
<div class="section" id="resetting-the-ups-battery-constant">
<h3><a class="toc-backref" href="#id147">Resetting the UPS Battery Constant</a></h3>
<p>In some cases none of the battery runtime calibration methods result in
the UPS reporting a reasonably correct battery runtime. It has been
speculated that this is because the battery constant value has drifted
so far from normal that the microprocessor in the UPS cannot correct it.</p>
<p>The good news is that if you are located in the USA, all you have to do
is contact APC Technical Support and they will send you a serial port
<em>dongle</em> which plugs into the serial port of your UPS and reprograms the
battery constant value for you to the correct value.</p>
<p>The bad news is that for many users outside the USA, this service does not
appear to be available. It is, however, recommended that you first try
contacting APC Technical Support to verify the correct battery constant
value. The APC representatives in the Support Forum on the APC website
are also very helpful in this regard.</p>
<p><em>If all else fails</em>, the information below is for you.</p>
<p><strong>WARNING:</strong> Only the values for the Smart-UPS 700 model SU700 and
Smart-UPS 1400 model SU1400, both with international firmware (and
therefore international voltage), have been verified. YOU, gentle reader,
USE THIS INFORMATION AT YOUR OWN RISK in the full knowledge that you
may render your UPS inoperable and perhaps irreparable, and you will
have no-one to blame but yourself. <em>Caveat Utilitor!</em></p>
<p>The battery constant is the hex number in the column labelled "0",
presumably for register 0, in the following table:</p>
<pre class="literal-block">
UPS Model 4 5 6 0 Hex Firmware
SU250 EE F8 B1
SU400 EE F8 9F E1
SU600 EA F4 9F E5
SU900 F3 FC 9F ED
SU1250 EE FA 9F F5
SU2000 F1 F9 9F FD
SU450,700 28 F2 FA 96 07,RM=47 52.11.I
SU450XL,700XL 28 EE F8 9F 700XL=27 51.9.I
SU1000,INET 35 EF F9 A0 0B 60.11.I
SU1000XL 34 EE FC 9A 2B 61.9.I
SU1400 35 EE FC 9A 70.11.I
SU1400RM 28 ED FA 89
SU1400R2IBX135 08 B4 10 A3
SU1400RMXLI3U 45 F6 F4 80 73.x.I
SU1400RMXLI3U 20 F3 FD 81 73.x.I
SU2200I 35 EE FB AF 90.14.I
SU2200XL,3000 35 EE FB AF 3000=17 90.14.I
SU3000RMXLI3Ublk 35 F3 F4 AF 77 93.14.I
SU5000I white 20 F2 FA 91 1F 110.14.I
SU1400XL,XLI,RM 45 F6 E4 80
SU420I 25 95 09 85 16 21.7.I
SU420SI 0E 95 0A 8C
SU620I 29 99 0B 8A 1A
BP420SI 0E 95 0A 8C 06 11.2.I
BP650SI 10 97 0C 91 0A 12.3.I
Power Stack 250 0C 95 0F B2 26.5.I
Power Stack 450 0D 96 10 99 36 26.5.I
SC250RMI1U 0C 95 0F B3 32 735.a.1
SC420I 0E 95 OA 8C 16 725.1.I
SC620I 10 97 OB 99 1A 726.x.I
SC1000I 08 95 10 94 8A 737.x.I
SC1500I 07 95 14 8F 1E 738.x.I
SU1000XL 17 EE F9 D5
MATRIX 3000,5000 E9 F5 B0
SU700RMI2U 07 B1 0D 92 8A 152.4.I
SU1000RMI2U 08 B5 0D C7 8E 157.3.I
SU1400RMI2U 08 B4 10 A3 92 162.3.I
SUA1000I 07 B5 13 BC 0A 652.12.I
SUA1000XLI 0B BD 0F 7F 4A 681.13.I
SUA750XLI 0A B9 0C 86 46 630.3.I
SUA750I 04 B6 14 82 06 651.12.I
SUA750RMI2U 07 B1 0D 82 86 619.12.I
SUA1500I 09 B9 13 A1 0E 601/653.x.I
SUA1500RMI2U 08 B4 10 A1 8E 617.3.I
SUA2200I 08 B8 12 B3 26 654.12.I
SUA2200RMI2U 09 BC 11 81 A6 665.4.I
SUA2200XLI 0A B7 0F 7F 66 690.x.I
SUA3000RMI2U 04 B9 0E 70 AA 666.4.I
SUA3000RMXLI3U 0A B6 0E 89 xx xxx.x.x
SUOL1000I 06 B6 1B A6
SUOL2000XL 0D BD 14 75 52 416.5.I
SURT1000XLI 0A BB 19 A8 4E 411.x.I
SURT3000XLI 06 B6 0F CC 56 450.2.I
SURT5000XLI 05 BA 15 86 5A 451.13.W
SURT7500XLI 03 BB 20 97 63
SURT10000XLI 06 B8 19 AB 476.12.W
SUM1500RMXLI2U 03 B7 0D A5 62 716.3.I
SUM3000RMXLI2U 03 B7 0D A5 6A 715.3.I
BP500AVR 26 17.1.I
</pre>
<p>The instructions for resetting the battery constant are as follows:</p>
<ol class="arabic simple">
<li>Shutdown the apcupsd daemon;</li>
<li>Run apctest;</li>
<li>Choose option 6 to enter terminal mode;</li>
<li>Enter Y (UPS should respond SM);</li>
<li>Enter 1 (one, not el; wait 4 seconds);</li>
<li>Enter 1 (one, not el; UPS should respond PROG);</li>
<li>Enter 0 (zero, not oh; UPS should respond with current constant);</li>
<li>Write down the existing value so that if something goes wrong, you can at least put it back to that value;</li>
<li>Enter + (plus) or - (minus) to increment/decrement the value;</li>
<li>Enter R to reprogram constant value (UPS should respond Bye);</li>
<li>Enter Y (UPS should respond SM);</li>
<li>Enter 0 (zero, not oh; UPS should respond with the new constant);</li>
<li>Enter Esc to exit terminal mode;</li>
<li>Choose option 7 to exit apctest.</li>
</ol>
</div>
</div>
<div class="section" id="frequently-asked-questions">
<h2><a class="toc-backref" href="#id148">Frequently-Asked Questions</a></h2>
<p>See the bugs section of this document for a list of
known bugs and solutions.</p>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Question:</th><td class="field-body"><p class="first">Why all the craziness with custom serial cables?</p>
</td>
</tr>
<tr class="field"><th class="field-name">Answer:</th><td class="field-body"><p class="first">It was nothing more nor less than a form of customer
control. For a long time APC wanted to keep other people from
talking to its UPSes so it could lock out potential competition for
its PowerChute software. Scrambling the leads on its serial cables
was a cheap way to accomplish this -- in fact, they tended to be
wired so that if you tried a straight-through cable, opening a
serial link to the UPS would be interpreted as a shutdown command!</p>
<p>(Hardware companies often think like this -- they lock up
interfaces by instinct, cornering a small market rather than
growing a bigger one. It's fundamentally stupid and self-defeating,
but it's the kind of stupid that tends to sound good at an
executive meeting.)</p>
</td>
</tr>
<tr class="field"><th class="field-name">Question:</th><td class="field-body"><p class="first">What UPS brands does apcupsd support?</p>
</td>
</tr>
<tr class="field"><th class="field-name">Answer:</th><td class="field-body"><p class="first">Currently apcupsd supports only APC UPSes. However,
some companies such as Hewlett Packard put their own brand name on
APC manufactured UPSes. Thus even if you do not have an APC branded
UPS, it may work with apcupsd. You will need to know the
corresponding APC model number. apcupsd supports all the popular
APC models. See the installation and configurations sections of
this document for more details.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Question:</th><td class="field-body"><p class="first">Does apcupsd support Windows?</p>
</td>
</tr>
<tr class="field"><th class="field-name">Answer:</th><td class="field-body"><p class="first">Yes.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Question:</th><td class="field-body"><p class="first">I don't have a cable, which one should I build?</p>
</td>
</tr>
<tr class="field"><th class="field-name">Answer:</th><td class="field-body"><p class="first">First you must know if you have an apcsmart UPS or a
voltage-signalling UPS. If you have a apcsmart UPS, we
recommend building a Custom Smart cable. (see <a class="reference internal" href="#smart-custom-cable-for-smartupses">Smart-Custom Cable for
SmartUPSes</a>) If you have a voltage-signaling UPS, we recommend that
you build a Custom Simple cable. (see <a class="reference internal" href="#simple-custom-voltage-signalling-cable-for-dumb-upses">Simple-Custom Voltage-Signalling
Cable for "dumb" UPSes</a>)</p>
</td>
</tr>
<tr class="field"><th class="field-name">Question:</th><td class="field-body"><p class="first">How much CPU resources does apcupsd use?</p>
</td>
</tr>
<tr class="field"><th class="field-name">Answer:</th><td class="field-body"><p class="first">Depending on your CPU speed, you may see more or less
of the CPU consumed by apcupsd. On a 400MHz Unix system, the CPU
usage should fall well below 0.1%. On slower systems, the
percentage will increase proportionally to the decrease in the CPU
speed. On a 400Mhz Win98 machine, the CPU usage will be on the
order of 0.5-1.0%. This is higher than for Unix systems. However,
compared to the 30% CPU usage by APC's PowerChute (the version on
the CDROM shipped with my UPS), apcupsd's 0.5-1.0% is very modest.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Question:</th><td class="field-body"><p class="first">What language is apcupsd written in?</p>
</td>
</tr>
<tr class="field"><th class="field-name">Answer:</th><td class="field-body"><p class="first">It is written in C and C++.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Question:</th><td class="field-body"><p class="first">To test apcupsd, I unplugged the UPS to simulate a
power outage. After the machine went into the shutdown process I
plugged the UPS back into the commercial power source. This caused
the shutdown process to hang after the daemon tried to shut-off the
ups. Have you run into this problem, and if so do you have a
remedy?</p>
</td>
</tr>
<tr class="field"><th class="field-name">Answer:</th><td class="field-body"><p class="first">Normally, once the shutdown process has begun, we
cannot stop it -- how do you stop a
shutdown that has killed off half of the daemons running on your
system? Most likely you will be left with an unusable system. In
addition, when apcupsd is re-executed in the halt script after the
disks are synced, it tries to shut off the UPS power, but the UPS
will generally refuse to do so if the AC power is on. Since we
cannot be 100% sure whether or not the UPS will shut off the power,
we don't attempt to reboot the system if we detect that the power
is back as it might then get caught by a delayed power off (at
least for Smart UPSes).</p>
</td>
</tr>
<tr class="field"><th class="field-name">Question:</th><td class="field-body"><p class="first">After running apcupsd for a while, I get the following
error: "Serial communications with UPS lost." What is the problem?</p>
</td>
</tr>
<tr class="field"><th class="field-name">Answer:</th><td class="field-body"><p class="first">We use standard Unix serial port read() and write()
calls so once a connection is made, we generally have few problems.
However, there have been reports that APC's SNMP Management Card
can cause serial port problems. If you have such a card, we suggest
that you remove it and see if the problem goes away. It is also
possible that some other process such as a getty is reading the
serial port.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Question:</th><td class="field-body"><p class="first">I get the following error:</p>
<pre class="literal-block">
Starting apcupsd power management.
Mar 20 21:19:40 box apcupsd[297]: apcupsd FATAL ERROR in apcserial.c at line 83.
Cannot open UPS tty /dev/cua01: No such file or directory.
</pre>
<p>What is the problem?</p>
</td>
</tr>
<tr class="field"><th class="field-name">Answer:</th><td class="field-body"><p class="first">The two most likely causes of your problem are: 1. You
have the wrong serial port device name in the apcupsd.conf file. 2.
The device name is not defined on your system. Suggestions for
proceeding:For the first item, check what your serial port device
should be named. You might be able to find the name with an:</p>
<pre class="literal-block">
ls /dev
</pre>
<p>Normally there will be hundreds or even thousands of names that
print. If that doesn't produce anything useful, you can try step 2.
Perhaps your device is not defined. To get more information on your
devices try '<tt class="docutils literal">man MAKEDEV</tt>' or '<tt class="docutils literal">find / <span class="pre">-name</span> MAKEDEV</tt>'. It is often
located in <tt class="docutils literal">/dev/MAKEDEV</tt>. Looking at the documentation may tell
you what the correct name is, or at least allow you to create the
device.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Question:</th><td class="field-body"><p class="first">How do I ensure that the slaves shutdown before the master?</p>
</td>
</tr>
<tr class="field"><th class="field-name">Answer:</th><td class="field-body"><p class="first">Slaves make their shutdown decision independently from the master.
Therefore you can use the <tt class="docutils literal">TIMEOUT</tt>, <tt class="docutils literal">MINUTES</tt>, and <tt class="docutils literal">BATTERYLEVEL</tt>
settings in the slaves' apcupsd.conf to configure them to shut down
before the master.</p>
</td>
</tr>
<tr class="field"><th class="field-name">Question:</th><td class="field-body"><p class="first">How do I ensure that my database server is correctly shutdown?</p>
</td>
</tr>
<tr class="field"><th class="field-name">Answer:</th><td class="field-body"><p class="first last">You simply add whatever commands are necessary in the
appropriate case statements in /etc/apcupsd/apccontrol, which is a
standard script file that is called to actually do the shutdown.
Alternatively, you can add your own script file that will be called
before doing the commands in apccontrol. Your script file must have
the same name as the appropriate case statement in apccontrol; it
must be executable; and it must be in the same directory as
apccontrol.</p>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="customizing-event-handling">
<h2><a class="toc-backref" href="#id149">Customizing Event Handling</a></h2>
<p>When apcupsd detects anomalies from your UPS device, it will make
some decisions that usually result in one or more calls to the
script located in <tt class="docutils literal">/etc/apcupsd/apccontrol</tt>. The <tt class="docutils literal">apccontrol</tt> file
is a shell script that acts on the first argument that apcupsd
passes to it. These actions are set up by default to sane behavior
for all situations apcupsd is likely to detect from the UPS.
However, you can change the apccontrol behavior for every single
action.</p>
<p>To customize, so create a file with the same name as the action,
which is passed as a command line argument. Put your script in the
<tt class="docutils literal">/etc/apcupsd</tt> directory.</p>
<p>These events are sent to the system log, optionally sent to the
temporary events file (<tt class="docutils literal">/etc/apcupsd/apcupsd.events</tt>), and they also
generate a call to <tt class="docutils literal">/etc/apcupsd/apccontrol</tt> which in turn will call
any scripts you have placed in the <tt class="docutils literal">/etc/apcupsd</tt> directory.</p>
<p>Normally, <tt class="docutils literal">/etc/apcupsd/apccontrol</tt> is called only by apcupsd.
Consequently, you should not invoke it directly. However, it is
important to understand how it functions, and in some cases, you
may want to change the messages that it prints using <tt class="docutils literal">wall</tt>. We
recommend that you do so by writing your own script to be invoked
by <tt class="docutils literal">apccontrol</tt> rather than by modifying apccontrol directly. This
makes it easier for you to upgrade to the next version of apcupsd</p>
<p>In other case, you may want to write your own shell scripts that
will be invoked by apccontrol. For example, when a power fail
occurs, you may want to send an email message to root.</p>
<p>To write your own routine for the <tt class="docutils literal">powerout</tt> action, you create
shell script named <tt class="docutils literal">powerout</tt> and put it in the lib directory
(normally /etc/apcupsd). When the <tt class="docutils literal">powerout</tt> action is invoked by
apcupsd, apccontrol will first give control to your script. If you
want apccontrol to continue with the default action, simply exit
your script with an exit status of zero. If you do not want
apccontrol to continue with the default action, your script should
exit with the special exit code of 99. However, in this case,
please be aware that you must ensure proper shutdown of your
machine if necessary.</p>
<p>Some sample scripts (onbattery and mainsback) that email power
failure messages can be found in /etc/apcupsd after an install or
in the platforms/etc directory of the source code.</p>
<div class="section" id="apccontrol-command-line-options">
<h3><a class="toc-backref" href="#id150">apccontrol Command Line Options</a></h3>
<p>When apcupsd detects an event, it calls the apccontrol script with
four arguments as:</p>
<p><tt class="docutils literal">apccontrol</tt> <em>event</em> <em>ups-name</em> <em>connected</em> <em>powered</em></p>
<p>where:</p>
<dl class="docutils">
<dt><em>event</em></dt>
<dd>is the event that occurred and it may be any one
of the values described in the next section.</dd>
<dt><em>ups-name</em></dt>
<dd>is the name of the UPS as specified in the
configuration file (not the name in the EEPROM).</dd>
<dt><em>connected</em></dt>
<dd>is 1 if apcupsd is connected to the UPS
via a serial port (or a USB port). In most configurations, this
will be the case. In the case of a Slave machine where apcupsd is
not directly connected to the UPS, this value will be 0.</dd>
<dt><em>powered</em></dt>
<dd>is 1 if the computer on which apcupsd is
running is powered by the UPS and 0 if not. At the moment, this
value is unimplemented and always 0.</dd>
</dl>
<p>The following <em>event</em> names are supported:</p>
<dl class="docutils">
<dt><strong>annoyme</strong></dt>
<dd><p class="first">When a shutdown is scheduled, and the time
specified on the ANNOYME directive in the apcupsd.conf file
expires, this event is generated.</p>
<p class="last"><em>Default:</em> <tt class="docutils literal">wall</tt> a message</p>
</dd>
<dt><strong>changeme</strong></dt>
<dd><p class="first">When apcupsd detects that the mains are on,
but the battery is not functioning correctly, this event is
generated. It is repeated every x hours.</p>
<p class="last"><em>Default:</em> <tt class="docutils literal">wall</tt> a message</p>
</dd>
<dt><strong>commfailure</strong></dt>
<dd><p class="first">This event is generated each time the
communications line with the computer is severed. This event is not
detected on dumb signaling UPSes.</p>
<p class="last"><em>Default:</em> <tt class="docutils literal">wall</tt> a message</p>
</dd>
<dt><strong>commok</strong></dt>
<dd><p class="first">After a commfailure event is issued, when the
communications to the computer is re-established, this event will
be generated.</p>
<p class="last"><em>Default:</em> <tt class="docutils literal">wall</tt> a message</p>
</dd>
<dt><strong>doreboot</strong></dt>
<dd><p class="first">This event is depreciated and should not be used.</p>
<p class="last"><em>Default:</em> Shuts down the system using <tt class="docutils literal">shutdown <span class="pre">-h</span></tt> or similar</p>
</dd>
<dt><strong>doshutdown</strong></dt>
<dd><p class="first">When the UPS is running on batteries and
one of the limits expires (time, run, load), this event is
generated to cause the machine to shutdown.</p>
<p class="last"><em>Default:</em> Shuts down the system using <tt class="docutils literal">shutdown <span class="pre">-h</span></tt> or similar</p>
</dd>
<dt><strong>emergency</strong></dt>
<dd><p class="first">Called for an emergency system shutdown. (What triggers such a shutdown
is unclear...) After completing this event, apcupsd will immediately
initiate a <tt class="docutils literal">doshutdown</tt> event.</p>
<p class="last"><em>Default:</em> <tt class="docutils literal">wall</tt> a message</p>
</dd>
<dt><strong>failing</strong></dt>
<dd><p class="first">This event is generated when the UPS is
running on batteries and the battery power is exhausted. The event
following this one will be a shutdown.</p>
<p class="last"><em>Default:</em> <tt class="docutils literal">wall</tt> a message</p>
</dd>
<dt><strong>loadlimit</strong></dt>
<dd><p class="first">This event is generated when the battery
charge is below the low limit specified in the apcupsd.conf file.
After completing this event, apcupsd will immediately
initiate a <tt class="docutils literal">doshutdown</tt> event.</p>
<p class="last"><em>Default:</em> <tt class="docutils literal">wall</tt> a message</p>
</dd>
<dt><strong>powerout</strong></dt>
<dd><p class="first">This event is generated immediately when
apcupsd detects that the UPS has switched to batteries. It may be
due to a short powerfailure, an automatic selftest of the UPS, or a
longer powerfailure.</p>
<p class="last"><em>Default:</em> <tt class="docutils literal">wall</tt> a message</p>
</dd>
<dt><strong>onbattery</strong></dt>
<dd><p class="first">This event is generated 5 or 6 seconds
after an initial powerfailure is detected. It means that apcupsd
definitely considers the UPS to be on batteries. The onset of this
event can be delayed by the <tt class="docutils literal">ONBATTERYDELAY</tt> apcupsd.conf
configuration directive.</p>
<p class="last"><em>Default:</em> <tt class="docutils literal">wall</tt> a message</p>
</dd>
<dt><strong>offbattery</strong></dt>
<dd><p class="first">This event is generated when the mains
return only if the onbattery event has been generated.</p>
<p class="last"><em>Default:</em> <tt class="docutils literal">wall</tt> a message</p>
</dd>
<dt><strong>mainsback</strong></dt>
<dd><p class="first">This event is generated when the mains
power returns after a powerout condition. The shutdown event may or
may not have been generated depending on the parameters you have
defined and the length of the power outage.</p>
<p class="last"><em>Default:</em> nothing</p>
</dd>
<dt><strong>remotedown</strong></dt>
<dd><p class="first">This event is generated on a slave
machine when it detects either that the master has shutdown, or
that a onbattery situation exists and the communications line has
been severed.</p>
<p class="last"><em>Default:</em> <tt class="docutils literal">wall</tt> a message</p>
</dd>
<dt><strong>runlimit</strong></dt>
<dd><p class="first">This event is generated when the <tt class="docutils literal">MINUTES</tt>
value defined in the apcupsd.conf file expires while in a power
fail condition. The <tt class="docutils literal">MINUTES</tt> is the remaining runtime as internally
calculated by the UPS and monitored by apcupsd. After completing this
event, apcupsd will immediately initiate a <tt class="docutils literal">doshutdown</tt> event.</p>
<p class="last"><em>Default:</em> <tt class="docutils literal">wall</tt> a message</p>
</dd>
<dt><strong>timeout</strong></dt>
<dd><p class="first">This event is generated when the <tt class="docutils literal">TIMEOUT</tt> value
defined in the apcupsd.conf file expires while in a power fail
condition. It indicates that the total time in a power failure has
been exceeded and the machine should be shutdown. After completing this
event, apcupsd will immediately initiate a <tt class="docutils literal">doshutdown</tt> event.</p>
<p class="last"><em>Default:</em> <tt class="docutils literal">wall</tt> a message</p>
</dd>
<dt><strong>startselftest</strong></dt>
<dd><p class="first">This event is generated when
apcupsd detects a self test by the UPS. Normally due to the 6
second onbattery delay default time, self test events are not
detected.</p>
<p class="last"><em>Default:</em> nothing</p>
</dd>
<dt><strong>endselftest</strong></dt>
<dd><p class="first">This event is generated when the end
of a self test is detected.</p>
<p class="last"><em>Default:</em> nothing</p>
</dd>
<dt><strong>battdetach</strong></dt>
<dd><p class="first">This event is generated when apcupsd
detects that the UPS battery has been disconnected.</p>
<p class="last"><em>Default:</em> nothing</p>
</dd>
<dt><strong>battattach</strong></dt>
<dd><p class="first">This event is generated when apcupsd
detects that the UPS battery has been reconnected after a
battdetach event.</p>
<p class="last"><em>Default:</em> nothing</p>
</dd>
</dl>
</div>
</div>
<div class="section" id="controlling-multiple-upses-on-one-machine">
<h2><a class="toc-backref" href="#id151">Controlling Multiple UPSes on one Machine</a></h2>
<p><em>The following discussion does not apply to Windows servers. Apcupsd on Windows
is limited to a single instance and cannot support monitoring multiple UPSes.</em></p>
<p>If you have multiple UPSes in use, you may wish to consolidate the monitoring
of all of these UPSes onto a single machine, which we shall call the "UPS
server". Generally one of the UPSes is powering the "UPS server" itself (and
possibly other machines as well). The remaining UPSes are powering additional
machines.</p>
<p>Apcupsd can work quite well in this environment by running one instance of
apcupsd on the UPS server for each UPS to be controlled. That is, you install
a single copy of apcupsd but launch it multiple times using different
configuration files and scripts. (Older versions of apcupsd required you to
actually compile the daemon multiple times with different <tt class="docutils literal">configure</tt> options.
This is no longer required, as all necessary adjustments can be made in
<tt class="docutils literal">apcupsd.conf</tt>.)</p>
<p>Additionally, you will run one instance of apcupsd on each of the machines
you wish to be shut down. You will configure each of these apcupsd's to use
the 'net' driver to read UPS status from the proper instance of apcupsd on the
UPS server. See <a class="reference internal" href="#nis-server-client-configuration-using-the-net-driver">NIS Server/Client Configuration Using the Net Driver</a> for
more information on the 'net' driver and setting up net clients.</p>
<div class="section" id="multiple-ups-example">
<h3><a class="toc-backref" href="#id152">Multiple UPS Example</a></h3>
<p>There are many ways one could set up multiple apcupsd instances. Here I will
present the way I have used with great success on Red Hat Linux.</p>
<p>I have two apcupsd.conf files (this is for a 2 UPS setup, easily
expandable to N):</p>
<pre class="literal-block">
[adk0212@mail apcupsd]$ ls -l /etc/apcupsd/*.conf
-rw-r--r-- 1 root root 11799 Aug 3 08:39 /etc/apcupsd/apcupsd.ups0.conf
-rw-r--r-- 1 root root 11822 Aug 25 14:31 /etc/apcupsd/apcupsd.ups1.conf
</pre>
<p>In my case, ups0 is the UPS powering the UPS server running the multiple
apcupsd instances, so only ups0 should initiate a shutdown of the local
machine. The differences between the confs are minor since both UPSes
are USB (although that is not a requirement; mixing cable types works
fine too):</p>
<pre class="literal-block">
[adk0212@mail apcupsd]$ diff -u apcupsd.ups0.conf apcupsd.ups1.conf
--- apcupsd.ups0.conf 2007-08-03 08:39:26.000000000 -0400
+++ apcupsd.ups1.conf 2007-08-25 14:31:17.000000000 -0400
-UPSNAME ups0
+UPSNAME ups1
-DEVICE /dev/ups0
+DEVICE /dev/ups1
-SCRIPTDIR /etc/apcupsd
+SCRIPTDIR /etc/apcupsd/null
-PWRFAILDIR /etc/apcupsd
+PWRFAILDIR /etc/apcupsd/null
-NOLOGINDIR /etc
+NOLOGINDIR /etc/apcupsd/null
-ANNOY 300
+ANNOY 0
-NISPORT 3551
+NISPORT 3552
-EVENTSFILE /var/log/apcupsd.events
+EVENTSFILE /var/log/apcupsd.2.events
</pre>
<p>The important difference to note is that ups1 has its <tt class="docutils literal">SCRIPTDIR</tt>,
<tt class="docutils literal">PWRFAILDIR</tt>, and <tt class="docutils literal">NOLOGINDIR</tt> set to a special "null" directory that I have
created. This directory contains a copy of the event handling scripts
modified to avoid shutting down the local machine. (Details below). Also
the UPSes are given different <tt class="docutils literal">EVENTSFILE</tt> and <tt class="docutils literal">NISPORT</tt> settings. Plus I
disable the "annoy" feature on ups1. Since the state of that UPS does not
impact local users, there's no reason to annoy them.</p>
<p>I have the following files in the special "null" directory:</p>
<pre class="literal-block">
[adk0212@mail apcupsd]$ ls -l /etc/apcupsd/null
total 32
-rwxr--r-- 1 root root 4176 Aug 3 08:24 apccontrol
-rwxr-xr-x 1 root root 475 Aug 3 08:28 changeme
-rwxr-xr-x 1 root root 502 Aug 3 08:28 commfailure
-rwxr-xr-x 1 root root 503 Aug 3 08:28 commok
-rwxr--r-- 1 root root 8 Aug 3 08:22 doshutdown
-rwxr-xr-x 1 root root 470 Aug 3 08:27 offbattery
-rwxr-xr-x 1 root root 435 Aug 3 08:27 onbattery
</pre>
<p>The important change here is the addition of a 'doshutdown' script which
overrides apccontrol's shutdown action:</p>
<pre class="literal-block">
[adk0212@mail null]$ cat /etc/apcupsd/null/doshutdown
exit 99
</pre>
<p>The "exit 99" tells apccontrol to skip its normal processing for that
event. apccontrol itself is unchanged; it is a direct copy of the
original. The other scripts are also direct copies and have simply been
modified to generate status email from NISPORT 3552 instead of 3551.</p>
<p>I also have a custom init.d start/stop script to manage multiple
instances. The start, stop, and status handlers are modified to iterate
over all /etc/apcupsd/apcupsd.*.conf files. This is derived from the
standard apcupsd redhat rc script:</p>
<pre class="literal-block">
#! /bin/sh
#
# apcupsd This shell script takes care of starting and stopping
# the apcupsd UPS monitoring daemon.
#
# chkconfig: 2345 60 99
# description: apcupsd monitors power and takes action if necessary
#
if test -f /etc/whitebox-release ; then
f=/etc/whitebox-release
else
f=/etc/redhat-release
fi
if test `cat $f | grep release |\
cut -f 3 -d ' '`x = "Enterprise"x ; then
DISTVER="Enterprise "`cat $f | grep release |\
cut -f 6 -d ' '`
else
DISTVER=`cat /etc/redhat-release | grep release |\
cut -f 5 -d ' '`
fi
# Source function library
. /etc/rc.d/init.d/functions
case "$1" in
start)
rm -f /etc/apcupsd/powerfail
rm -f /etc/nologin
for conf in /etc/apcupsd/apcupsd.*.conf ; do
inst=`basename $conf`
echo -n "Starting UPS monitoring ($inst):"
daemon /sbin/apcupsd -f $conf -P /var/run/apcupsd-$inst.pid
RETVAL=$?
echo
[ $RETVAL -eq 0 ] && touch /var/lock/subsys/apcupsd-$inst
done
;;
stop)
for conf in /etc/apcupsd/apcupsd.*.conf ; do
inst=`basename $conf`
echo -n "Shutting down UPS monitoring ($inst):"
killproc -p /var/run/apcupsd-$inst.pid apcupsd
echo
rm -f /var/run/apcupsd-$inst.pid
rm -f /var/lock/subsys/apcupsd-$inst
done
;;
restart|force-reload)
$0 stop
sleep 15
$0 start
;;
reload)
echo "$0: reload not implemented"
exit 3
;;
status)
for conf in /etc/apcupsd/apcupsd.*.conf ; do
inst=`basename $conf`
status -p /var/run/apcupsd-$inst.pid apcupsd-$inst
RETVAL=$?
if [ $RETVAL -eq 0 ]
then
NISPORT=`grep ^NISPORT < $conf | sed -e "s/NISPORT *\([0-9]\)/\1/"`
/sbin/apcaccess status localhost:$NISPORT | egrep "(STATUS)|(UPSNAME)"
fi
done
;;
*)
echo "Usage: $0 {start|stop|restart|status}"
exit 1
;;
esac
exit 0
</pre>
<p>That's about all there is to it. There are still some rough edges to
clean up, but overall this is a <em>lot</em> easier with apcupsd 3.14.x than it
used to be.</p>
</div>
</div>
<div class="section" id="support-for-snmp-upses">
<h2><a class="toc-backref" href="#id153">Support for SNMP UPSes</a></h2>
<p>To run apcupsd with a SNMP UPS, you need the
following things:</p>
<ul class="simple">
<li>An SNMP UPS, for example a Web/SNMP (AP9716) or PowerNet SNMP
(AP9605) card installed into the SmartSlot. Apcupsd also has support
for some non-APC SNMP UPSes using RFC1628 or MGE MIBs, however the
majority of the information in this section is for APC UPSes.</li>
</ul>
<div class="section" id="planning-and-setup-for-snmp-wiring">
<h3><a class="toc-backref" href="#id154">Planning and Setup for SNMP Wiring</a></h3>
<p>SNMP packet requests are relayed to
the UPS from monitoring APCUPSD servers over Ethernet via a switch,
hub, or router. Protecting these Ethernet devices with UPS supplied
power is necessary to ensure reliable SNMP communication during
power failures. Servers may fail to shutdown quietly during power
failures if SNMP communication is lost.</p>
</div>
<div class="section" id="planning-and-setup-for-snmp-configuration">
<h3><a class="toc-backref" href="#id155">Planning and Setup for SNMP Configuration</a></h3>
<p>To establish communication to the UPS SNMP card
installed in the UPS, the SNMP card will need the following:</p>
<ul class="simple">
<li>Assign SNMP card IP Address</li>
<li>Set SNMP card General Parameters</li>
<li>Set SNMP card Shutdown Parameters</li>
<li>Set SNMP card Event Trap Receivers (apcupsd-3.12.0 and later)</li>
</ul>
<div class="section" id="assign-snmp-card-ip-address">
<h4><a class="toc-backref" href="#id156">Assign SNMP Card IP Address</a></h4>
<p>The following instructions come from the APC knowledge base:</p>
<pre class="literal-block">
The Network Management Card (AP9617, AP9618, AP9619) must be
configured with network settings before it can communicate on the
network. Once the cards have been configured with an IP address,
Subnet Mask, and Default Gateway the cards can be access, managed,
and controlled from other computers on the network.
There are two ways to configure the Network Management Card (NMC)
with its initial settings: the (windows) Wizard and Address
Resolution Protocol (ARP).
1. The wizard in included on the CD that comes with the card. The
wizard must run on a Windows operating system. You can configure
the card using the wizard over the network via FTP. If using the
wizard please note, the un-configured NMC must be on the same
subnet as the computer running the wizard.
2. Address resolution protocol (arp) can also be used to configure
the NMC. The MAC Address of the NMC is needed for this method of
configuration. The MAC address is located on the quality assurance
slip that is shipped with the NMC, and is also located on the white
sticker on the NMC itself. From a computer on the same subnet as
the un-configured NMC, follow the instructions:
Open up a command prompt and type the following (replacing
<IPaddress> and <MacAddress> with the actual values):
arp -s <IPaddress> <MacAddress>
Next, use Ping with a size of 113 bytes to assign the IP address
defined by the ARP command.
- Linux command format: ping <IPaddress> -s 113
- Windows command format: ping <IPaddress> -l 113
</pre>
</div>
<div class="section" id="set-snmp-card-general-parameters">
<h4><a class="toc-backref" href="#id157">Set SNMP card General Parameters</a></h4>
<p>After the SNMP Network Management Card is configured with an IP address,
the SNMP Card is ready for general configuration. This is accomplished by
telneting to the SNMP Card.</p>
<pre class="literal-block">
~$ telnet <IPaddress>
</pre>
<p>Login using "apc" for both the username and password and the
following menu will display:</p>
<pre class="literal-block">
*******************************************************************************
American Power Conversion Network Management Card AOS v2.6.4
(c) Copyright 2004 All Rights Reserved Smart-UPS & Matrix-UPS APP v2.6.1
-------------------------------------------------------------------------------
Name : Date : 07/03/2006
Contact : Time : 04:43:33
Location : User : Administrator
Up Time : 0 Days 01 Hours 57 Minutes Stat : P+ N+ A+
Smart-UPS 1000 named : On Line, No Alarms Present
------- Control Console -------------------------------------------------------
1- Device Manager
2- Network
3- System
4- Logout
<ESC>- Main Menu, <ENTER>- Refresh, <CTRL-L>- Event Log
>
*******************************************************************************
</pre>
<p>Select <strong>Option 2</strong> for Network. Next select <strong>Option 1</strong> for TCP/IP
settings.</p>
<p>At this point the following settings will be to be specified:</p>
<ul class="simple">
<li>Verify System IP: <IPaddress></li>
<li>Specify Subnet Mask: i.e. "225.225.225.0"</li>
<li>Specify Default Gateway</li>
<li>Specify Host Name</li>
<li>Specify Domain Name</li>
</ul>
<p>Specifying these parameters will complete the General Parameters
setup. Additionally the SNMP Network Management Card can now be
connected to from a web browser for monitoring and additional
configuration.</p>
</div>
<div class="section" id="set-snmp-card-shutdown-parameters">
<h4><a class="toc-backref" href="#id158">Set SNMP card Shutdown Parameters</a></h4>
<p>There are two shutdown parameters that must be set in the SNMP card
to ensure that connected servers shutdown quietly. These parameters
can be set via the telnet terminal or the web browser interface.</p>
<ul class="simple">
<li>Shutdown Delay (sec)</li>
<li>Return Battery Capacity (%)</li>
</ul>
<p>One of the draw-backs of SNMP communication to the UPS is that the
Stand-alone or Primary server must issue the power down command to
the UPS early in server halt procedure. This server must issue an
early command to the SNMP UPS to power down before its ethernet
service is halted. This creates a potential problem where the UPS
may kill power to any connected servers before these affected
servers' halt scripts complete a successful shutdown.</p>
<p>The SNMP <strong>Shutdown Delay</strong> parameter is used to delay the UPS from
killing power to its load by a prescribed period of seconds. The
delay should be long enough to ensure that the Stand-alone or
Primary server has enough time to successfully halt. The prescribed
time should at least be 180 seconds. Any additional computers
connected to the SNMP UPS must not be configured to issue the
command to initiate UPS power down. These servers can be thought of
as secondary stand-alone server. The APCUPSD daemons of secondary
servers should be configured to initiate server halt a prescribed
period of time before the Primary server issues the UPS power down
command.</p>
<p>The <strong>Return on Battery Capacity</strong> is useful during intermittent
sequential power failures. This parameter insures that the UPS will
not restore power to its loads until it has recharged it battery to
a prescribed percentage. This parameter should be set to a value
greater than value that the APCUPSD daemons configured
"BATTERYLEVEL" shutdown of any connected servers. This will ensure
that when the UPS restores power, any additional power failures
will successfully re-trigger a server shutdown.</p>
</div>
<div class="section" id="configure-event-trap-receivers">
<h4><a class="toc-backref" href="#id159">Configure Event Trap Receivers</a></h4>
<p>(Requires apcupsd-3.12.0 and later)</p>
<p>By default, APCUPSD will poll the SNMP UPS card once per minute. In
this case, server notification of UPS alarms could potentially be
delayed one minute. Event trap catching mitigates this shortcoming.
Any UPS alarms are instantly sent to prescribe servers connected
SNMP UPS. These servers are referred to as Event Trap Receivers.
The SNMP UPS card can be configure to send event traps to a maximum
of four receivers that will "catch" these events.</p>
<p>Event trap receivers IP address can be set using a telnet terminal
or web browser interface.</p>
<p>Also, be aware that servers configured to be Event Trap Receivers
should have static IP set. Severs obtaining IPs from DHCP server
will not catch instantaneous Events if the IP address changes from
the address set in the SNMP UPS.</p>
</div>
</div>
<div class="section" id="connecting-apcupsd-to-a-snmp-ups">
<h3><a class="toc-backref" href="#id160">Connecting APCUPSD to a SNMP UPS</a></h3>
<p>The previous sections describe configuration of the actual SNMP
card. The remaining sections describe configuration of the APCUPSD
to communicate using SNMP Protocol.</p>
<p>To enable the SNMP support it is enough to configure
the correct device in your apcupsd.conf configuration file. The
directive needed for this configuration is:</p>
<pre class="literal-block">
DEVICE <host>:<port>:<vendor>:<community>
</pre>
<p>...where the directive is made by four parts. All but the first may be omitted
completely or left empty to accept the default.</p>
<ul>
<li><p class="first"><em>host</em>: IP address or DNS hostname of the UPS (required)</p>
</li>
<li><p class="first"><em>port</em>: Remote SNMP port (optional, default: 161)</p>
</li>
<li><p class="first"><em>vendor</em>: The type of SNMP MIB available on the UPS (optional, default:
autodetect). Allowable choices for vendor are:</p>
<ul class="simple">
<li>APC : APC PowerNet MIB, used on most APC brand UPSes</li>
<li>RFC : RFC1628 MIB, used by some non-APC UPSes</li>
<li>MGE : MGE MIB, used by many MGE brand UPSes</li>
<li>blank : Autodetect</li>
</ul>
<p>Append "_NOTRAP" to the vendor name to disable SNMP trap catching
(ex: "APC_NOTRAP"). See <a class="reference internal" href="#snmp-trap-catching">SNMP Trap Catching</a>.</p>
</li>
<li><p class="first"><em>community</em>: The read-write community string, usually "private". You can
specify a read-only community string, usually "public", if you do not
require killpower support. If the community string is omitted, apcupsd will
attempt to autotedect by trying "private" and "public".
(optional, default: autodetect).</p>
</li>
</ul>
<p>A NIS Server/Client (Master/Slave) configuration
with multiple servers is still applicable. However, an alternative
configuration is possible with an SNMP
enabled UPS. In this arrangement, all connected servers will be
configured as a standalone server. Each will independently
communicate to the UPS. One (primary) server will be chosen to
manage the task of commanding the UPS to power down. All remaining
(secondary) servers will be configured to quietly power down before
the primary server issues the UPS power down command.</p>
</div>
<div class="section" id="building-with-snmp-support">
<h3><a class="toc-backref" href="#id161">Building with SNMP support</a></h3>
<p>Follow the instructions in <a class="reference internal" href="#building-and-installing-apcupsd">Building and Installing apcupsd</a>, being sure
to include the following options (in addition to any others you need) on the
'<tt class="docutils literal">./configure</tt>' line:</p>
<pre class="literal-block">
./configure --enable-snmp
</pre>
</div>
<div class="section" id="snmp-trap-catching">
<h3><a class="toc-backref" href="#id162">SNMP Trap Catching</a></h3>
<p>apcupsd-3.11.14 introduces support for SNMP trap catching.
Previous versions polled the UPS status
once per minute, leading to significant delays before UPS state
changes were recognized. With SNMP trap handling, apcupsd monitors
the SNMP trap port and will re-poll the UPS whenever a trap is
received. This happens, for example, when the UPS switches on or
off battery.</p>
<p>In order for this feature to work, you must configure your UPS to
deliver traps to the server running apcupsd. This is generally done
by connecting to your SNMP card via a web browser or telnet
connection. You will need to enter your server's IP address as a
trap receiver and make sure trap delivery is enabled.</p>
<p>Trap catching can lead to problems if you are already running
another SNMP trap daemon on your server. Only one daemon can listen
to the trap port, so whichever one is started first will succeed
and the others will fail. Apcupsd will fall back to polling
behavior if it is unable to open the trap port. You can also
forcibly disable trap catching by appending <tt class="docutils literal">_NOTRAP</tt> to your vendor
string in the apcupsd.conf <tt class="docutils literal">DEVICE</tt> directive.</p>
</div>
<div class="section" id="known-problems">
<h3><a class="toc-backref" href="#id163">Known Problems</a></h3>
<p>Currently (as of 3.10.0) the code to power off the UPS needs
special configuration. The killpower command for SNMP UPSes can not
be issued during shutdown as typically at some time during shutdown
operations the network stack is stopped. To overcome this problem
it is needed to modify the /etc/rc.d/apcupsd system control script
to tell apcupsd to issue the power down command (killpower) to the
UPS immediately before apcupsd initiates the system shutdown. For
this reason it is paramount to set your UPS grace time to a value
greater than 120 seconds to allow for clean shutdown operations
before the UPS removes the power from its plugs. To enable correct
shutdown operation during powerdown do the following:</p>
<ul class="simple">
<li>Connect to your Web/SNMP card using your favorite web browser,
go to the UPS configuration menu and change the "Shutdown Delay"
parameter to 180 seconds or more, depending on how much time your
system shutdown requires to umount all the filesystems.</li>
<li><strong>Option 1 (non-windows)</strong> Edit the server halt script. Relocate
the ups_kill_power() function higher in the shutdown sequence,
primarily before the command to bring down the ethernet service.
This is the preferred method for shutting down the UPS. The UPS
will power down after the prescribed "Shut Down Delay" time (in
seconds) has elapsed.</li>
<li><strong>Option 2</strong> Change /etc/rc.d/apcupsd script adding the
<tt class="docutils literal"><span class="pre">--kill-on-powerfail</span></tt> to the apcupsd invocation. This method is
not preferred because the UPS is commanded to power down without
delay. This creates the potential for UPS powering down before the
server calling for UPS power down completes its shutdown. However,
in the case of Microsoft Windows OS, this is the only method
available for powering down the UPS.</li>
<li>Restart your apcupsd</li>
</ul>
<p>With this setup your UPS operations should be safe.</p>
</div>
</div>
<div class="section" id="apcupsd-system-logging">
<h2><a class="toc-backref" href="#id164">apcupsd System Logging</a></h2>
<p>The apcupsd philosophy is that all logging should be done through the
<tt class="docutils literal">syslog</tt> facility (see: '<tt class="docutils literal">man syslog</tt>') This is now implemented with
the exceptions that STATUS logging, for compatibility with
prior versions is still done to a file, and EVENTS logging can
be directed to a temporary file so that it can be reported by the
network information server.</p>
<div class="section" id="logging-types">
<h3><a class="toc-backref" href="#id165">Logging Types</a></h3>
<p>apcupsd splits its logging into four separate types called:</p>
<ol class="arabic simple">
<li>DEBUG</li>
<li>DATA</li>
<li>STATUS</li>
<li>EVENTS</li>
</ol>
<p>Debug logging consists of debug messages. Normally these are turned
on only by developers, and currently there exist very few of these
debug messages.</p>
<div class="section" id="data-logging">
<h4><a class="toc-backref" href="#id166">Data Logging</a></h4>
<p>This feature is somewhat outdated and not often used.</p>
<p>Data logging consists of periodically logging important data
concerning the operation of the UPS. For the definitive definition
of the format, see log_data() in apcreports.c. The format varies
according to the UPS model and the information available from the
UPS.</p>
<p>For UPS models, NBKPRO, SMART, SHARESMART, and MATRIX, the output
is written in a format very similar to what PowerChute writes. That
is:</p>
<p>MinLineVoltage, MaxLineVoltage, OutputVoltage, BatteryVoltage,
LineFrequency, LoadPercent, UPSTemperature, AmbientTemperature, Humidity,
LineVoltage, BatteryCharge, toggle</p>
<p>Any value that is not supported by your UPS such as
AmbientTemperature and Humidity will be blank or possibly as 0.0.
In any case the commas before and after that field will still be
output. The toggle value alternates from 0 to 1 on each line. This
was added at user request so that no two adjacent samples are
identical.</p>
<p>An actual example from the log file is:</p>
<pre class="literal-block">
Nov 2 12:43:05 matou apcupsd[23439]: 224.9,227.5,226.2,27.74,50.00,100.0,30.6,,,226.2,50.0,1
</pre>
</div>
<div class="section" id="status-logging">
<h4><a class="toc-backref" href="#id167">Status Logging</a></h4>
<p>Status logging consists of logging all available information known
about your UPS as a series of ASCII records. This information is
also made available by the apcupsd network information server.</p>
<p>For more details on STATUS logging, see the <a class="reference internal" href="#apcupsd-status-logging">apcupsd Status Logging</a>
section for details.</p>
</div>
<div class="section" id="events-logging">
<h4><a class="toc-backref" href="#id168">EVENTS Logging</a></h4>
<p>Events logging consists of logging events as they happen. For
example, successful startup, power fail, battery failure, system
shutdown, ...</p>
<p>See the <a class="reference internal" href="#customizing-event-handling">Customizing Event Handling</a> section for more details.</p>
</div>
</div>
<div class="section" id="implementation-details">
<h3><a class="toc-backref" href="#id169">Implementation Details</a></h3>
<p>In order to ensure that the data logged to syslog() can be directed
to different files, I have assigned syslog() levels to each of our
four types of data as follows:</p>
<ol class="arabic simple">
<li>DEBUG logging has level LOG_DEBUG</li>
<li>DATA logging has level LOG_INFO</li>
<li>STATUS logging has level LOG_NOTICE</li>
<li>EVENTS logging has levels LOG_WARNING, LOG_ERR, LOG_CRIT, and LOG_ALERT</li>
</ol>
<p>It should be noted that more work needs to be done on the precise
definitions of each of the levels for EVENTS logging. Currently, it
is roughly broken down as follows:</p>
<p>LOG_WARNING general information such as startup, etc.</p>
<p>LOG_ERR an error condition detected, e.g. communications problem
with the UPS.</p>
<p>LOG_CRIT a serious problem has occurred such as power failure,
running on UPS batteries, ...</p>
<p>LOG_ALERT a condition that needs immediate attention such as
pending system shutdown, ...</p>
<p>The default Facility for syslog() logging is DAEMON, although this
can be changed with the FACILITY directive in apcupsd.conf. In the
following example, we should the facility as local0.</p>
<p>More work needs to be done to the code to ensure that it
corresponds to the above levels.</p>
<p>As a practical example of how to setup your syslog() to use the new
logging feature, suppose you wish to direct all DATA logging to a
file named /var/log/apcupsd.data, all EVENTS to the standard
/var/log/messages file (to be mixed with other system messages),
and at the same time send all EVENTS to /var/log/apcupsd.events,
and finally, you want to send all STATUS logging to the named pipe
/var/log/apcupsd.status</p>
<p>First as root, you create the named pipe:</p>
<pre class="literal-block">
mkfifo /var/log/apcupsd.status
</pre>
<p>Change its permissions as necessary or use the -m option to set
them when creating the pipe.</p>
<p>Then you modify your /etc/syslog.conf file to direct the
appropriate levels of messages where you want them. To accomplish
the above, my syslog.conf file looks like:</p>
<pre class="literal-block">
# exclude all apcupsd info by default
*.info;local0.none /var/log/messages
# Everything for apcupsd goes here
local0.info;local0.!notice /var/log/apcupsd.data
local0.notice;local0.!warn |/var/log/apcupsd.status
local0.warn /var/log/apcupsd.events
local0.warn /var/log/messages
</pre>
</div>
</div>
<div class="section" id="the-windows-version-of-apcupsd">
<h2><a class="toc-backref" href="#id170">The Windows Version of apcupsd</a></h2>
<p>The Windows version of apcupsd has been tested on Win95, Win98,
WinMe, WinNT, WinXP, and Win2000 systems. This version of apcupsd
has been built to run natively on Windows (no Cygwin or other
emulation layer needed). Even though the Win32 version of apcupsd
is a port that relies on many Unix features, it is just the same a
true Windows program. When running, it is perfectly integrated with
Windows and displays its icon in the system icon tray, and provides
a system tray menu to obtain additional information on how apcupsd
is running (status and events dialog boxes).</p>
<p>Once installed apcupsd normally runs as a system service. This
means that it is immediately started by the operating system when
the system is booted, and runs in the background even if there is
no user logged into the system.</p>
<div class="section" id="installing-apcupsd-on-windows">
<h3><a class="toc-backref" href="#id171">Installing Apcupsd on Windows</a></h3>
<p>Normally, you will install the Windows version of apcupsd from the
binaries. Starting with version 3.11.15, the Windows binaries are
distributed with a full GUI installer driven by NSIS, the
Nullsoft Scriptable Install System (<a class="reference external" href="http://nsis.sourceforge.net">http://nsis.sourceforge.net</a>).</p>
<p>Installation is very simple and straight-forward: Simply
double-click the installer executable and follow the instructions.</p>
</div>
<div class="section" id="configuring-apcupsd-on-windows">
<h3><a class="toc-backref" href="#id172">Configuring Apcupsd on Windows</a></h3>
<p>If you are installing Apcupsd for the first time, the installer
will give you an opportunity to edit the apcupsd.conf configuration
file to contain the values appropriate for your site. (Subsequent
installations will maintain your existing apcupsd.conf, so you need
not edit it again unless there are new features or syntax changes
that must be accounted for.)</p>
<p>The default configuration calls for a USB connected UPS. This is
the most common connection for modern UPSes, especially those used
with Windows computers. All other apcupsd drivers are available
(apcsmart, dumb, net, snmp, pcnet) and can be used simply by
editing the configuration file <tt class="docutils literal">UPSCABLE</tt>, <tt class="docutils literal">UPSTYPE</tt>, and <tt class="docutils literal">DEVICE</tt>
settings as described elsewhere in this manual.</p>
<p>Note that on Windows, serial ports are specified using <tt class="docutils literal">COM1</tt>, <tt class="docutils literal">COM2</tt>,
etc. notation instead of the UNIX-style /dev/tty* notation.</p>
<p>Note also if you are using WinNT or Win2000, the operating system
may probe the serial port attempting to attach a serial mouse. This
will cause apcupsd to be unable to communicate with the serial
port. If this happens, or out of precaution, you can edit the
<tt class="docutils literal"><span class="pre">c:\\boot.ini</span></tt> file. Find the line that looks something like the
following:</p>
<pre class="literal-block">
multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT Workstation Version 4.00"
</pre>
<p>and add the following to the end of the line: <tt class="docutils literal">/NoSerialMice:COM1</tt>
(or COM2 depending on what you want to use). The new line should
look similar to...</p>
<pre class="literal-block">
multi(0)disk(0)rdisk(0)partition(1)\WINNT="Windows NT Workstation Version 4.00" /NoSerialMice:COM1
</pre>
<p>...where the only thing you have changed is to append to the end of
the line. This addition will prevent the operating system from
interfering with apcupsd</p>
</div>
<div class="section" id="starting-apcupsd-on-windows">
<h3><a class="toc-backref" href="#id173">Starting Apcupsd on Windows</a></h3>
<p>The installer will give you an opportunity start the Apcupsd
service immediately. If you choose to start it manually, you may do
so by selecting the "Start Apcupsd" link from the Start->Programs->Apcupsd
folder.</p>
<p>On Windows NT/2000/XP, you may alternatively go to the Control
Panel, open the Services folder, select Apcupsd UPS Server, and
then click on the <strong>Start</strong> button as shown below:</p>
<img alt="./wininstall6.png" src="./wininstall6.png" />
<p>If the Services dialog reports a problem, it is normally because
your <tt class="docutils literal">DEVICE</tt> statement does not contain the correct serial port
name.</p>
<p>You probably should also click on the <strong>Startup...</strong> button to
ensure that the correct defaults are set. The dialogue box that
appears should have <strong>Startup Type</strong> set to <strong>Automatic* and
**Logon</strong> should be set to <strong>System Account</strong>. If these values are not set
correctly by default, please change them otherwise apcupsd will not
work.</p>
<p>For WinXP and Win2K systems, the dialogs are a bit different from
those shown here for WinNT, but he concept is the same. You get to
the Services dialog by clicking on: Control Panel ->
Administrative Tools -> Component Services. The apcupsd service
should appear in the right hand window when you click on <strong>Services
(Local)</strong> in the left hand menu window.</p>
<p>That should complete the installation process. When the system tray
icon turns from a question mark <img alt="image4" src="./commlost.png" /> into a plug <img alt="image5" src="./online.png" />,
right click on it and a menu will appear. Select the <strong>Events</strong>
item, and the Events dialogue box should appear. There should be no
error messages. By right clicking again on the system tray plug and
selecting the <strong>Status</strong> item, you can verify that all the values
for your UPS are correct.</p>
<p>When the UPS switches to the battery, the battery icon <img alt="image6" src="./onbatt.png" />
will appear in the system tray. While the UPS is online, if the
battery is not at least 99% charged, the plug icon will become a
plug with a lightning bolt in the middle <img alt="image7" src="./charging.png" /> to indicate that
the battery is charging.</p>
</div>
<div class="section" id="apctray">
<h3><a class="toc-backref" href="#id174">Apctray</a></h3>
<p>Starting with version 3.14.2, the tray icon is provided by a separate
program called 'apctray'. This cleanly separates the user interface
from the daemon (service) and is required for tray icon support on
Windows Vista. Note that if you close or disable the tray icon this
does <strong>not</strong> stop or disable the apcupsd service which will continue
to monitor the UPS and shutdown the computer when appropriate. To
stop or disable the service, use the service control panel.</p>
<p>apctray has the capability of monitoring multiple apcupsd instances
using apcupsd's Network Information Server (NIS). It will create a
new icon for each instance being monitored. By default, apctray
monitors the local apcupsd (localhost on port 3551). To add
additional monitors, you can right-click an existing icon and choose
"Add Monitor". To remove a monitor, right-click its icon and choose
"Remove Monitor". To change thr settings for an existing monitor
(ip address, port, refresh rate), right-click its icon and choose
"Configure...".</p>
<p>apctray can be installed standalone (without apcupsd) if you wish
to use it only to monitor remote apcupsd instances. This can be
convenient for keeping an eye on a room full of UPSes from your
desktop. Download and run the normal apcupsd installer and simply
uncheck all components except apctray. Then add as many monitors as
you wish as described above.</p>
</div>
<div class="section" id="testing-apcupsd-on-windows">
<h3><a class="toc-backref" href="#id175">Testing Apcupsd on Windows</a></h3>
<p>It would be hard to overemphasize the need to do a full testing of
your installation of apcupsd as there are a number of reasons why
it may not behave properly in a real power failure situation.</p>
<p>Please read the <a class="reference internal" href="#testing-apcupsd">Testing Apcupsd</a> section of this document for
general instructions on testing the Win32 version. However, on
Win32 systems, there is no Unix system log file, so if something
goes wrong, look in the file <tt class="docutils literal"><span class="pre">c:\apcupsd\etc\apcupsd\apcupsd.events</span></tt>
where apcupsd normally logs its events, and you will generally find
more detailed information on why the program is
not working. The most common cause of problems is either improper
configuration of the cable type, or an incorrect address for the
serial port. Additionally, check the application event log, if
you're running a platform that supports it such as Windows 2000 or
XP.</p>
</div>
<div class="section" id="upgrading">
<h3><a class="toc-backref" href="#id176">Upgrading</a></h3>
<p>An upgrade may be accomplished by uninstalling the old version
(using the Add/Remove Programs Control Panel or clicking the
"Uninstall Apcupsd" link from Start -> Programs -> Apcupsd. Near the
end of the uninstall you will be prompted about removing
configuration and event files. You should answer "No" in order to
preserve your existing apcupsd.conf file.</p>
<p>After the uninstall completes you may install the new version of
Apcupsd as described above. If you preserved your existing
apcupsd.conf file, the new apcupsd.conf will be installed as
apcupsd.conf.new.</p>
</div>
<div class="section" id="post-installation">
<h3><a class="toc-backref" href="#id177">Post-Installation</a></h3>
<p>After installing
apcupsd and before running it, you should check the contents of the
config file <tt class="docutils literal"><span class="pre">c:\apcupsd\etc\apcupsd\apcupsd.conf</span></tt>. You will
probably need to change your UPSCABLE directive, your UPSTYPE and
possibly your DEVICE directives. Please refer to the configuration
section of this manual for more details.</p>
</div>
<div class="section" id="problem-areas">
<h3><a class="toc-backref" href="#id178">Problem Areas</a></h3>
<p>On some Windows systems, the
domain resolution does not seem to work if you have not configured
a DNS server in the Network section of the Control Panel. This
problem should be apparent only when running a slave configuration.
In this case, when you specify the name of the master in your
apcupsd.conf file, apcupsd will be unable to resolve the name to a
valid IP address. To circumvent this problem, simply enter the
address as an IP address rather than a hostname, or alternatively,
ensure that you have a valid DNS server configured on your system.</p>
<p>On WinNT, WinXP, and Win2K systems, you can examine the System
Applications log to which apcupsd writes Windows error messages
during startup.</p>
<p>Regardless of which Windows system you are running, apcupsd logs
most error messages to <tt class="docutils literal"><span class="pre">c:\apcupsd\etc\apcupsd\apcupsd.events</span></tt>.
This type error messages such as configuration
file not found, etc are written to this file. Note that on some
systems (WinXP, possibly others) Apcupsd is unable to write to this
file when running as a service.</p>
</div>
<div class="section" id="email-notification-of-events">
<h3><a class="toc-backref" href="#id179">Email Notification of Events</a></h3>
<p>It is possible to receive email notification of apcupsd events
using some simple Visual Basic scripts contributed by Ed Dondlinger
<<a class="reference external" href="mailto:edondlinger@thepylegroup.com">edondlinger@thepylegroup.com</a>>. The scripts are automatically installed in
the <tt class="docutils literal">etc/apcupsd</tt> directory of your apcupsd installation but are disabled
by default. To enable them, first open them in a text editor such as Notepad
and edit the <tt class="docutils literal">USER VARIABLES</tt> section to set your email preferences including
address, server information, etc. Then rename the script files without the
<tt class="docutils literal">*.example</tt> suffix. Scripts are supplied for onbattery, offbattery, and
commfailure events. You can copy the scripts to other filenames and modify
the email body text to respond to other events as described in <a class="reference internal" href="#customizing-event-handling">Customizing
Event Handling</a>.</p>
</div>
<div class="section" id="killpower-under-windows">
<h3><a class="toc-backref" href="#id180">Killpower under Windows</a></h3>
<p>If your batteries become
exhausted during a power failure and you want your machine to
automatically reboot when the power comes back, it is useful to
implement the killpower feature of the UPS where apcupsd sends the
UPS the command to shut off the power. In doing so, the power will
be cut to your PC and if your BIOS is properly setup, the machine
will automatically reboot when the power comes back. This is
important for servers.</p>
<p>This feature is implemented on Unix systems by first requesting a
system shutdown. As a part of the shutdown, apcupsd is terminated
by the system, but the shutdown process executes a script where
apcupsd is recalled after the disks are synced and the machine is
idle. Apcupsd then requests the UPS to shut off the power
(killpower).</p>
<p>Unfortunately on Windows, there is no such shutdown script that we
are aware of and no way for apcupsd to get control after the
machine is idled. If this feature is important to you, it is
possible to do it by telling apcupsd to immediately issue the
killpower command after issuing the shutdown request. The danger in
doing so is that if the machine is not sufficiently idled when the
killpower takes place, the disks will need to be rescanned (and
there is a possibility of lost data however small). Generally,
UPSes have a shutdown grace period which gives sufficient time for
the OS to shutdown before the power is cut.</p>
<p>To implement this feature, you need to add the <tt class="docutils literal"><span class="pre">-p</span></tt> option to the
apcupsd command line that is executed by the system. Currently the
procedure is manual. You do so by editing the registry and changing
the line:</p>
<pre class="literal-block">
c:\apcupsd\apcupsd.exe /service
</pre>
<p>found under the key:</p>
<pre class="literal-block">
HKEY_LOCAL_MACHINE Software\Microsoft\Windows\CurrentVersion\RunServices
</pre>
<p>to</p>
<pre class="literal-block">
c:\apcupsd\apcupsd.exe /service -p
</pre>
<p>If you have a Smart UPS, you can configure the kill power grace
period, and you might want to set it to 3 minutes. If you have a
dumb UPS, there is no grace period and you should not use this
procedure. If you have a Back-UPS CS or ES, these UPSes generally
have a fixed grace period of 2 minutes, which is probably
sufficient.</p>
</div>
<div class="section" id="power-down-during-shutdown">
<h3><a class="toc-backref" href="#id181">Power Down During Shutdown</a></h3>
<p>Our philosophy is to shutdown
a computer but not to power it down itself (as opposed to having
the UPS cut the power as described above). That is we prefer to
idle a computer but leave it running. This has the advantage that
in a power fail situation, if the killpower function described
above does not work, the computer will continue to draw down the
batteries and the UPS will hopefully shutoff before the power is
restore thus permitting an automatic reboot.</p>
<p>Nevertheless some people prefer to do a full power down. To do so,
you might want to get a copy of PsShutdown, which does have a power
down option. You can find it and a lot more useful software at:
<a class="reference external" href="http://technet.microsoft.com/en-us/sysinternals/bb897541.aspx">http://technet.microsoft.com/en-us/sysinternals/bb897541.aspx</a>. To use their shutdown
program rather than the apcupsd supplied version, you simply edit:</p>
<pre class="literal-block">
c:\apcupsd\etc\apcupsd\apccontrol
</pre>
<p>with any text editor and change our calls to shutdown to
psshutdown.</p>
</div>
<div class="section" id="command-line-options-specific-to-the-windows-version">
<h3><a class="toc-backref" href="#id182">Command Line Options Specific to the Windows Version</a></h3>
<p>These options are not normally
seen or used by the user, and are documented here only for
information purposes. At the current time, to change the default
options, you must either manually run apcupsd or you must manually
edit the system registry and modify the appropriate entries.</p>
<p>In order to avoid option clashes between the options necessary for
apcupsd to run on Windows and the standard apcupsd options, all
Windows specific options are signaled with a forward slash
character (<tt class="docutils literal">/</tt>), while as usual, the standard apcupsd options are
signaled with a minus (<tt class="docutils literal">-</tt>), or a minus minus (<tt class="docutils literal"><span class="pre">--</span></tt>). All the
standard apcupsd options can be used on the Windows version. In
addition, the following Windows only options are implemented:</p>
<table class="docutils option-list" frame="void" rules="none">
<col class="option" />
<col class="description" />
<tbody valign="top">
<tr><td class="option-group">
<kbd><span class="option">/service</span></kbd></td>
<td>Start apcupsd as a service</td></tr>
<tr><td class="option-group">
<kbd><span class="option">/run</span></kbd></td>
<td>Run the apcupsd application</td></tr>
<tr><td class="option-group">
<kbd><span class="option">/install</span></kbd></td>
<td>Install apcupsd as a service in the system registry</td></tr>
<tr><td class="option-group">
<kbd><span class="option">/remove</span></kbd></td>
<td>Uninstall apcupsd from the system registry</td></tr>
<tr><td class="option-group">
<kbd><span class="option">/about</span></kbd></td>
<td>Show the apcupsd about dialogue box</td></tr>
<tr><td class="option-group">
<kbd><span class="option">/kill</span></kbd></td>
<td>Stop any running apcupsd</td></tr>
<tr><td class="option-group">
<kbd><span class="option">/help</span></kbd></td>
<td>Show the apcupsd help dialogue box</td></tr>
</tbody>
</table>
<p>It is important to note that under normal circumstances the user
should never need to use these options as they are normally handled
by the system automatically once apcupsd is installed. However, you
may note these options in some of the .pif files that have been
created for your use.</p>
</div>
</div>
<div class="section" id="installation-serial-line-upses">
<h2><a class="toc-backref" href="#id183">Installation: Serial-Line UPSes</a></h2>
<div class="section" id="overview-of-serial-interface-upses">
<h3><a class="toc-backref" href="#id184">Overview of Serial-Interface UPSes</a></h3>
<p>If you have a UPS that communicates via
serial port, you need to do two things before you can even think
about configuring the software. First, you need to figure out
whether it's a dumb (voltage-signalling) UPS or speaks the apcsmart
protocol. Second,
if you have an interface cable from APC, you need to figure out
what kind it is. If you don't have such a cable, you need to build
one. A straight-through serial cable won't work.</p>
<p>According to Bill Marr the Belkin F5U109, also sold as F5U409 also
works with apcupsd for kernel versions 2.4.25 or higher and kernels
2.6.1 and higher. These newer kernels are needed to have the patch
that makes the mct_u232 (Magic Control Technology) module and
other adapters work with RS-232 devices that do not assert the CTS
signal.</p>
</div>
<div class="section" id="connecting-a-serial-line-ups-to-a-usb-port">
<h3><a class="toc-backref" href="#id185">Connecting a Serial-Line UPS to a USB Port</a></h3>
<p>By using a special adaptor, you can
connect your serial-line UPS to a USB port. If you would like to
free up your serial port and connect your existing serial port UPS
to a USB port, it is possible if you have one of the later kernels.
You simply get a serial to USB adapter that is supported by the
kernel, plug it in and make one minor change to your apcupsd.conf
file and away you go. (Kern adds: Thanks to Joe Acosta for pointing
this out to me.)</p>
<p>The device that Joe Acosta and Kern are using is IOgear GUC232A USB
2 serial adapter. Bill Marr informs us that it also works with a
Back-UPS Pro 650 and the 940-0095B cable.</p>
<p>At Kern's site, running Red Hat 7.1 with kernel 2.4.9-12, he simply
changed his /etc/apcupsd/apcupsd.conf configuration line to be:</p>
<pre class="literal-block">
DEVICE /dev/ttyUSB0
</pre>
<p>Depending on whether or not you have hotplug working, you may
need to explicitly load the kernel modules <tt class="docutils literal">usbserial</tt> and
<tt class="docutils literal">pl2303</tt>. In Kern's case, this was not necessary.</p>
</div>
<div class="section" id="testing-serial-line-upses">
<h3><a class="toc-backref" href="#id186">Testing Serial-Line UPSes</a></h3>
<p>If you have a serial-line UPS, there are some tests you should run
before the general ones described in the <a class="reference internal" href="#testing-apcupsd">Testing Apcupsd</a> section.</p>
<p>To test your computer's connection with a serial-line UPS, you
first need to establish that the serial line is functioning, and
then that the UPS is responding to commands. This can be a bit
tricky, especially with a dumb voltage-signalling interface,
because it is completely quiescent when there are no commands being
passed, and the command repertoire doesn't include any self-tests.</p>
<p>Because it is easy to configure a serial cable incorrectly in such
a way as to cause premature shutdowns of the UPS power, we
<em>strongly</em> recommend, especially for voltage- signaling (dumb)
UPSes, that you do most of the initial testing with your computer
plugged into the wall rather than your UPS. Thus if the UPS power
is suddenly shut off, your computer will continue to run. We also
recommend using safe-apccontrol as described below, until you are
sure that the signaling is correct.</p>
<p>Also note that if you launch the execution of apcupsd while your
voltage-signaling UPS is on battery power, it is very likely that
your UPS will immediately shut off the power. This is due to the
initialization of the serial port line signals, which often looks
to the UPS like a shutdown command.</p>
<p>Finally, double-check the state of your cabling and UPS indicator
lights frequently during testing. For voltage-signaling UPSes,
apcupsd is not currently able to detect whether or not the serial
cable is connected. In addition, some simple signaling UPSes with
certain cable combinations are not able to detect the low battery
condition. For more details please see <a class="reference internal" href="#voltage-signalling-features-supported-by-apcupsd-for-various-cables">Voltage Signalling Features
Supported by Apcupsd for Various Cables</a>.</p>
</div>
<div class="section" id="establishing-serial-port-connection">
<h3><a class="toc-backref" href="#id187">Establishing Serial Port Connection</a></h3>
<p>Once you have compiled, installed,
and invoked apcupsd, you should wait to allow apcupsd to configure
itself and establish contact with the UPS.</p>
<p>If you see a message similar to the following about 30 seconds after starting
apcupsd...</p>
<pre class="literal-block">
apcupsd FATAL ERROR in apcserial.c at line 156
PANIC! Cannot communicate with UPS via serial port.
</pre>
<p>it means that apcupsd tried for about 30 seconds to establish
contact with the UPS via the serial port, but was unable to do so.
Before continuing, you must correct this problem. Some of the
possible sources of the problem are:</p>
<ul class="simple">
<li>You have not configured the correct serial port name on the
<tt class="docutils literal">DEVICE</tt> directive in your apcupsd configuration file.</li>
<li>The serial port that you have chosen has logins enabled. You
must disable logins on that port, otherwise, the system prevents
apcupsd from using it. Normally, the file /etc/inittab specifies
the ports for which a getty process is started (on Sun machines,
the serial port program equivalent to getty is called ttymon). You
must disable this for the port that you wish to use.</li>
<li>Make sure you are doing your testing as root otherwise, you
may have permissions problems accessing the serial port.</li>
<li>You may have cabling problems, either with an incorrect cable,
or the incorrect cable specification directive in the configuration
file.</li>
<li>You may have a problem with the /etc/apcupsd/acpupsd.conf file.
For example, check that you have specified the correct type of UPS
and the correct networking directives. For more details, see the
<a class="reference internal" href="#after-installation">After Installation</a> section.</li>
<li>If you have a SmartUPS 5000 RM 15U or similar model, that comes
with a "Web/SNMP management card" in one of the "Smart Slots", this
card may interfere with the serial port operation. If you are
having problems, please remove this card and try again. Supposedly
V3.0 of the card firmware has been corrected to properly release
the serial port.</li>
<li>Ensure that you have no other programs that are using the serial
port. One user reported that he had problems because the serial
port mouse (gpm) was using the same port as apcupsd. This causes
intermittent seemingly random problems.</li>
<li>Try connecting your UPS to another machine. If it works, then
you probably have a bad serial port card. As unlikely as this may
sound, at least two of our users have had to replace bad serial
port cards.</li>
<li>Try doing an '<tt class="docutils literal">lsof /dev/ttyS0</tt>' where you replace the
<tt class="docutils literal">/dev/ttyS0</tt> with your serial port name. If you get no output, the
port is free (or there is no physical port). If you get output,
then another program is using the port, and you should see which
one.</li>
<li>Try doing a '<tt class="docutils literal">dmesg | grep tty</tt>'. This may show you if a program
has grabbed the port. (Thanks to Joe Acosta for the suggestion.)</li>
<li>If all else fails, make sure your system is configured for
serial port support.</li>
</ul>
<p>The first thing to do is to look at your log file, usually
/var/log/messages because apcupsd writes more detailed information
to the log file whenever there is an error.</p>
<p>If you have a UPS that uses apcsmart protocol, you can manually test the
serial communications with the UPS by starting a serial port communications
program (such as minicom, tip, or cu) with the settings 2400 8N1 (2400 baud,
8 data bits, no parity, 1 stop bit). Be extremely careful what you send to
your UPS as certain characters may cause it to power down or may
even cause damage to the UPS. Try sending an upper case <tt class="docutils literal">Y</tt> to the
UPS (without a return at the end). It should respond with <tt class="docutils literal">SM</tt>. If
this is not the case, review the possible problems listed above. If
you fat finger the Y and enter y instead, no cause for alarm, you
will simply get the APC copyright notice.</p>
<p>Once you are sure that serial port communications is working,
proceed to the next test.</p>
</div>
<div class="section" id="once-you-have-established-serial-communications">
<h3><a class="toc-backref" href="#id188">Once you have established serial communications</a></h3>
<p>Once you have established that apcupsd can talk
to the UPS over the serial part, go do the series of functional
tests described in the main Testing section (see <a class="reference internal" href="#testing-apcupsd">Testing Apcupsd</a>).</p>
</div>
<div class="section" id="troubleshooting-serial-line-communications">
<h3><a class="toc-backref" href="#id189">Troubleshooting Serial Line communications</a></h3>
<p><em>The most frequently encountered problem with voltage-signalling
UPSes (e.g. BackUPS 650) is that you have incorrectly specified
which cable is being used.</em> All cables furnished by APC have the
cable number stamped on the side of the computer connector end of
the cable. Using this number with apcupsd will normally work fine.
If you do not know what cable you have, you can use the apctest
program to determine the type of the cable.</p>
<p>For simple signaling UPSes, you should <strong>not</strong> use <tt class="docutils literal">simple</tt> in the
cable specification (i.e. <tt class="docutils literal">UPSCABLE simple</tt>) unless you have made
the cable yourself according to the wiring diagram given in the
cables chapter of this manual.</p>
<div class="section" id="bizarre-intermittent-behavior">
<h4><a class="toc-backref" href="#id190">Bizarre Intermittent Behavior:</a></h4>
<p>In one case, a user reported that he received random incorrect
values from the UPS in the status output. It turned out that gpm,
the mouse control program for command windows, was using the serial
port without using the standard Unix locking mechanism. As a
consequence, both apcupsd and gpm were reading the serial port.
Please ensure that if you are running gpm that it is not configured
with a serial port mouse on the same serial port.</p>
</div>
</div>
</div>
<div class="section" id="cables">
<h2><a class="toc-backref" href="#id191">Cables</a></h2>
<p>You can either use the cable that came with your
UPS (the easiest if we support it) or you can make your own cable.
We recommend that you obtain a supported cable directly from APC.</p>
<p>If you already have an APC cable, you can determine what kind it is
by examining the flat sides of the two connectors where you will
find the cable number embossed into the plastic. It is generally on
one side of the male connector.</p>
<p>To make your own cable you must first know whether you have a UPS
that speaks the apcsmart protocol or a "dumb" UPS that uses serial
port line voltage signalling.</p>
<p>If you have an smart UPS, and you build your own cable, build a Smart-Custom
cable (see <a class="reference internal" href="#smart-custom-cable-for-smartupses">Smart-Custom Cable for SmartUPSes</a>). If you have a
voltage-signalling or dumb UPS, build a Simple-Custom cable (see
<a class="reference internal" href="#simple-custom-voltage-signalling-cable-for-dumb-upses">Simple-Custom Voltage-Signalling Cable for "dumb" UPSes</a>). If you have a
BackUPS CS with a RJ45 connector, you can build your own Custom-RJ45 cable
(see <a class="reference internal" href="#custom-rj45-smart-signalling-cable-for-backups-cs-models">Custom-RJ45 Smart Signalling Cable for BackUPS CS Models</a>).</p>
<div class="section" id="smart-custom-cable-for-smartupses">
<h3><a class="toc-backref" href="#id192">Smart-Custom Cable for SmartUPSes</a></h3>
<p><em>You do not have this cable unless you built it yourself.
The Smart-Custom cable is not an APC product.</em></p>
<pre class="literal-block">
SMART-CUSTOM CABLE
Signal Computer UPS
DB9F DB9M
RxD 2 -------------------- 2 TxD Send
TxD 3 -------------------- 1 RxD Receive
GND 5 -------------------- 9 Ground
</pre>
<p>When using this cable with apcupsd specify the following in
apcupsd.conf:</p>
<pre class="literal-block">
UPSCABLE smart
UPSTYPE apcsmart
DEVICE /dev/ttyS0 (or whatever your serial port is)
</pre>
<p>If you have an OS that requires DCD or RTS to be set before you can
receive input, you might try building the standard APC Smart
940-0024C cable listed below (see <a class="reference internal" href="#id40">940-0024C Cable Wiring</a>).</p>
</div>
<div class="section" id="simple-custom-voltage-signalling-cable-for-dumb-upses">
<h3><a class="toc-backref" href="#id193">Simple-Custom Voltage-Signalling Cable for "dumb" UPSes</a></h3>
<p><em>You do not have this cable unless you built it yourself.
The Simple-Custom cable is not an APC product.</em></p>
<p>For "dumb" UPSes using voltage signalling, if you are going to
build your own cable, we recommend to make the cable designed by
the apcupsd team as follows:</p>
<pre class="literal-block">
SIMPLE-CUSTOM CABLE
Signal Computer UPS
DB9F 4.7K ohm DB9M
DTR 4 --[####]--* DTR set to +5V by Apcupsd
|
CTS 8 ----------*--------- 5 Low Battery
GND 5 -------------------- 4 Ground
DCD 1 -------------------- 2 On Battery
RTS 7 -------------------- 1 Kill UPS Power
</pre>
<p>List of components one needs to make the Simple cable:</p>
<ol class="arabic simple">
<li>One (1) male DB9 connector, use solder type connector only.</li>
<li>One (1) female DB9/25F connector, use solder type connector
only.</li>
<li>One (1) 4.7K ohm 1/4 watt 5% resistor.</li>
<li>rosin core solder.</li>
<li>three (3) to five (5) feet of 22AWG multi-stranded four or more
conductor cable.</li>
</ol>
<p>Assembly instructions:</p>
<ol class="arabic simple">
<li>Solder the resistor into pin 4 of the female DB9 connector.</li>
<li>Next bend the resistor so that it connects to pin 8 of the
female DB9 connector.</li>
<li>Pin 8 on the female connector is also wired to pin 5 on the male
DB9 connector. Solder both ends.</li>
<li>Solder the other pins, pin 5 on the female DB9 to pin 4 on the
male connector; pin 1 on the female connector to pin 2 on the male
connector; and pin 7 on the female connector to pin 1 on the male
connector.</li>
<li>Double check your work.</li>
</ol>
<p>We use the DTR (pin 4 on the female connector) as our +5 volts
power for the circuit. It is used as the Vcc pull-up voltage for
testing the outputs on any "UPS by APC" in voltage-signalling mode.
This cable may not work on a BackUPS Pro if the default
communications are in apcsmart mode. This cable is also valid for
use on a ShareUPS BASIC Port. It is reported to work on
SmartUPSes, however the Smart Cable described above is preferred.</p>
<p>To have a better idea of what is going on inside apcupsd,
for the SIMPLE cable apcupsd reads three signals and sets three:</p>
<blockquote>
<dl class="docutils">
<dt>Reads:</dt>
<dd><p class="first">CD, which apcupsd uses for the On Battery signal when high.</p>
<p>CTS, which apcupsd uses for the Battery Low signal when high.</p>
<dl class="last docutils">
<dt>RxD (SR), which apcupsd uses for the Line Down</dt>
<dd>signal when high. This signal isn't used for much.</dd>
</dl>
</dd>
<dt>Sets:</dt>
<dd><dl class="first last docutils">
<dt>DTR, which apcupsd sets when it detects a power failure (generally</dt>
<dd>5 to 10 seconds after the CD signal goes high). It
clears this signal if the CD signal subsequently goes low
-- i.e. power is restored.</dd>
<dt>TxD (ST), which apcupsd clears when it detects that the CD signal</dt>
<dd>has gone low after having gone high - i.e. power is restored.</dd>
<dt>RTS, which apcupsd sets for the killpower signal -- to cause the UPS</dt>
<dd>to shut off the power.</dd>
</dl>
</dd>
</dl>
</blockquote>
<p>Please note that these actions apply only to the SIMPLE cable. The
signals used on the other cables are different.</p>
<p>Finally, here is another way of looking at the CUSTOM-SIMPLE
cable:</p>
<pre class="literal-block">
APCUPSD SIMPLE-CUSTOM CABLE
Computer Side | Description of Cable | UPS Side
DB9f | DB25f | | DB9m | DB25m
4 | 20 | DTR (5vcc) *below | n/c |
8 | 5 | CTS (low battery) *below | <- 5 | 7
2 | 3 | RxD (no line voltage) *below | <- 3 | 2
5 | 7 | Ground (Signal) | 4 | 20
1 | 8 | CD (on battery from UPS) | <- 2 | 3
7 | 4 | RTS (kill UPS power) | -> 1 | 8
n/c | 1 | Frame/Case Gnd (optional) | 9 | 22
Note: the <- and -> indicate the signal direction.
</pre>
<p>When using this cable with apcupsd specify the following in
apcupsd.conf:</p>
<pre class="literal-block">
UPSCABLE simple
UPSTYPE dumb
DEVICE /dev/ttyS0 (or whatever your serial port is)
</pre>
</div>
<div class="section" id="custom-rj45-smart-signalling-cable-for-backups-cs-models">
<h3><a class="toc-backref" href="#id194">Custom-RJ45 Smart Signalling Cable for BackUPS CS Models</a></h3>
<p>If you have a BackUPS CS, you are probably either using it with the
USB cable that is supplied or with the 940-0128A supplied by APC,
which permits running the UPS in dumb mode. By building your own
cable, you can now run the BackUPS CS models (and perhaps also the
ES models) using smart signalling and have all the same information
that is available as running it in USB mode.</p>
<p>The jack in the UPS is actually a 10 pin RJ45. However, you can
just as easily use a 8 pin RJ45 connector, which is more standard
(ethernet TX, and ISDN connector). It is easy to construct the
cable by cutting off one end of a standard RJ45-8 ethernet cable
and wiring the other end (three wires) into a standard DB9F female
serial port connector.</p>
<p>Below, you will find a diagram for the CUSTOM-RJ45 cable:</p>
<pre class="literal-block">
CUSTOM-RJ45 CABLE
Signal Computer UPS UPS
DB9F RJ45-8 RJ45-10
RxD 2 ---------------- 1 2 TxD Send
TxD 3 ---------------- 7 8 RxD Receive
GND 5 ---------------- 6 7 Ground
FG Shield ---------------- 3 4 Frame Ground
The RJ45-8 pins are: looking at the end of the connector:
8 7 6 5 4 3 2 1
___________________
| . . . . . . . . |
| |
-------------------
|____|
The RJ45-10 pins are: looking at the end of the connector:
10 9 8 7 6 5 4 3 2 1
_______________________
| . . . . . . . . . . |
| |
-----------------------
|____|
</pre>
<p>For the serial port DB9F connector, the pin numbers are stamped in
the plastic near each pin. In addition, there is a diagram near the
end of this chapter.</p>
<p>Note, one user, Martin, has found that if the shield is not
connected to the Frame Ground in the above diagram (not in our
original schematic), the UPS (a BackUPS CS 500 EI) will be unstable
and likely to rapidly switch from power to batteries (i.e.
chatter).</p>
<p>When using this cable with apcupsd specify the following in
apcupsd.conf:</p>
<pre class="literal-block">
UPSCABLE smart
UPSTYPE apcsmart
DEVICE /dev/ttyS0 (or whatever your serial port is)
</pre>
<p>The information for constructing this cable was discovered and
transmitted to us by slither_man. Many thanks!</p>
</div>
<div class="section" id="other-apc-cables-that-apcupsd-supports">
<h3><a class="toc-backref" href="#id195">Other APC Cables that apcupsd Supports</a></h3>
<p>apcupsd will also support the following off the shelf cables that
are supplied by APC</p>
<ul class="simple">
<li>940-0020[B/C] Simple Signal Only, all models.</li>
<li>940-0023A Simple Signal Only, all models.</li>
<li>940-0119A Simple Signal Only, Back-UPS Office, and BackUPS ES.</li>
<li>940-0024[B/C/G] Smart mode Only, SU and BKPro only.</li>
<li>940-0095[A/B/C] PnP (Plug and Play), all models.</li>
<li>940-1524C Smart mode Only</li>
<li>940-0128A Simple Signal Only, Back-UPS CS in serial mode.</li>
<li>All USB cables such as 940-0127[A/B]</li>
</ul>
</div>
<div class="section" id="voltage-signalling-features-supported-by-apcupsd-for-various-cables">
<h3><a class="toc-backref" href="#id196">Voltage Signalling Features Supported by Apcupsd for Various Cables</a></h3>
<p>The following table shows the features supported by the current
version of apcupsd for various cables running the UPS in
voltage-signalling mode.</p>
<table border="1" class="docutils">
<colgroup>
<col width="21%" />
<col width="16%" />
<col width="18%" />
<col width="16%" />
<col width="29%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Cable</th>
<th class="head">Power Loss</th>
<th class="head">Low Battery</th>
<th class="head">Kill Power</th>
<th class="head">Cable Disconnected</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>940-0020B</td>
<td>Yes</td>
<td>No</td>
<td>Yes</td>
<td>No</td>
</tr>
<tr><td>940-0020C</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>No</td>
</tr>
<tr><td>940-0023A</td>
<td>Yes</td>
<td>No</td>
<td>No</td>
<td>No</td>
</tr>
<tr><td>940-0119A</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>No</td>
</tr>
<tr><td>940-0127A</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>No</td>
</tr>
<tr><td>940-0128A</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>No</td>
</tr>
<tr><td>940-0095A/B/C</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>No</td>
</tr>
<tr><td>simple</td>
<td>Yes</td>
<td>Yes</td>
<td>Yes</td>
<td>No</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="voltage-signalling">
<h3><a class="toc-backref" href="#id197">Voltage Signalling</a></h3>
<p>Apparently, all APC voltage-signalling UPSes with DB9 serial ports
have the same signals on the output pins of the UPS. The difference
at the computer end is due to different cable configurations. Thus,
by measuring the connectivity of a cable, one can determine how to
program the UPS.</p>
<p>The signals presented or accepted by the UPS on its DB9 connector
using the numbering scheme listed above is:</p>
<pre class="literal-block">
UPS Pin Signal meaning
1 <- Shutdown when set by computer for 1-5 seconds.
2 -> On battery power (this signal is normally low but
goes high when the UPS switches to batteries).
3 -> Mains down (line fail) See Note 1 below.
5 -> Low battery. See Note 1 below.
6 -> Inverse of mains down signal. See Note 2 below.
7 <- Turn on/off power (only on advanced UPSes only)
Note 1: these two lines are normally open, but close when the
appropriate signal is triggered. In fact, they are open collector
outputs which are rated for a maximum of +40VDC and 25 mA. Thus
the 4.7K ohm resistor used in the Custom Simple cable works
quite well.
Note 2: the same as note 1 except that the line is normally closed,
and opens when the line voltage fails.
</pre>
</div>
<div class="section" id="the-back-ups-office-500-signals">
<h3><a class="toc-backref" href="#id198">The Back-UPS Office 500 signals</a></h3>
<p>The Back-UPS Office UPS has a telephone type jack as output, which
looks like the following:</p>
<pre class="literal-block">
Looking at the end of the connector:
6 5 4 3 2 1
_____________
| . . . . . . |
| |
| |----------|
|__|
</pre>
<p>It appears that the signals work as follows:</p>
<pre class="literal-block">
UPS Signal meaning
1 (brown) <- Shutdown when set by computer for 1-5 seconds.
2 (black) -> On battery power
3 (blue) -> Low battery
4 (red) Signal ground
5 (yellow) <- Begin signalling on other pins
6 (none) none
</pre>
</div>
<div class="section" id="analyses-of-apc-cables">
<h3><a class="toc-backref" href="#id199">Analyses of APC Cables</a></h3>
<div class="section" id="b-cable-wiring">
<h4><a class="toc-backref" href="#id200">940-0020B Cable Wiring</a></h4>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Supported Models:</th><td class="field-body">Simple Signaling such as BackUPS</td>
</tr>
<tr class="field"><th class="field-name">Contributed by:</th><td class="field-body">Lazar M. Fleysher</td>
</tr>
</tbody>
</table>
<p>Although we do not know what the black box semiconductor contains,
we believe that we understand its operation (many thanks to Lazar
M. Fleysher for working this out).</p>
<p>This cable can only be used on voltage-signalling UPSes, and
provides the On Battery signal as well as kill UPS power. Most
recent evidence (Lazar's analysis) indicates that this cable under
the right conditions may provide the Low Battery signal. This is
yet to be confirmed.</p>
<p><em>This diagram is for informational purposes and may not be complete.
We don't recommend that use it to build you build one yourself.</em></p>
<pre class="literal-block">
APC Part# - 940-0020B
Signal Computer UPS
DB9F DB9M
CTS 8 -------------------- 2 On Battery
DTR 4 -------------------- 1 Kill power
GND 5 ---------------*---- 4 Ground
|
--- *---- 9 Common
DCD 1 ----|///|----------- 5 Low Battery
|\\\|
RTS 7 ----|///| (probably a
--- semi-conductor)
</pre>
</div>
<div class="section" id="c-cable-wiring">
<h4><a class="toc-backref" href="#id201">940-0020C Cable Wiring</a></h4>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Supported Models:</th><td class="field-body">Simple Signaling such as BackUPS</td>
</tr>
</tbody>
</table>
<p>This cable can only be used on voltage-signalling UPSes, and
provides the On Battery signal, the Low Battery signal as well as
kill UPS power. You may specify <tt class="docutils literal">UPSCABLE <span class="pre">940-0020C</span></tt>.</p>
<p><em>This diagram is for informational purposes and may not be complete.
We don't recommend that use it to build you build one yourself.</em></p>
<pre class="literal-block">
APC Part# - 940-0020C
Signal Computer UPS
DB9F DB9M
CTS 8 -------------------- 2 On Battery
DTR 4 -------------------- 1 Kill power
GND 5 ---------------*---- 4 Ground
|
*---- 9 Common
RTS 7 -----[ 93.5K ohm ]----- 5 Low Battery
or semi-conductor
</pre>
</div>
<div class="section" id="a-cable-wiring">
<h4><a class="toc-backref" href="#id202">940-0023A Cable Wiring</a></h4>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Supported Models:</th><td class="field-body">Simple Signaling such as BackUPS</td>
</tr>
</tbody>
</table>
<p>This cable can only be used on voltage-signalling UPSes, and
apparently only provides the On Battery signal. As a consequence,
this cable is pretty much useless, and we recommend that you find a
better cable because all APC UPSes support more than just On
Battery. Please note that we are not sure the following diagram is
correct.</p>
<p><em>This diagram is for informational purposes and may not be complete.
We don't recommend that use it to build you build one yourself.</em></p>
<pre class="literal-block">
APC Part# - 940-0023A
Signal Computer UPS
DB9F DB9M
DCD 1 -------------------- 2 On Battery
3.3K ohm
TxD 3 --[####]-*
|
DTR 4 ---------*
GND 5 ---------------*---- 4 Ground
|
*---- 9 Common
</pre>
</div>
<div class="section" id="id40">
<h4><a class="toc-backref" href="#id203">940-0024C Cable Wiring</a></h4>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Supported Models:</th><td class="field-body">SmartUPS (all models with DB9 serial port)</td>
</tr>
</tbody>
</table>
<p>If you wish to build the standard cable furnished by APC
(940-0024C), use the following diagram.</p>
<pre class="literal-block">
APC Part# - 940-0024C
Signal Computer UPS
DB9F DB9M
RxD 2 -------------------- 2 TxD Send
TxD 3 -------------------- 1 RxD Receive
DCD 1 --*
|
DTR 4 --*
GND 5 -------------------- 9 Ground
RTS 7 --*
|
CTS 8 --*
</pre>
</div>
<div class="section" id="id41">
<h4><a class="toc-backref" href="#id204">940-0095A Cable Wiring</a></h4>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Supported Models:</th><td class="field-body">APC BackUPS Pro PNP</td>
</tr>
<tr class="field"><th class="field-name">Contributed by:</th><td class="field-body">Chris Hanson cph at zurich.ai.mit.edu</td>
</tr>
</tbody>
</table>
<p>This is the definitive wiring diagram for the 940-0095A cable
submitted by Chris Hanson, who disassembled the original cable,
destroying it in the process. He then built one from his diagram
and it works perfectly.</p>
<pre class="literal-block">
APC Part# - 940-0095A
UPS end Computer end
------- ------------
47k 47k
BATTERY-LOW (5) >----R1----*----R2----*----< DTR,DSR,CTS (4,6,8)
| |
| |
| / E
| |/
| B |
*-------| 2N3906 PNP
|
|\
\ C
|
|
*----< DCD (1) Low Batt
|
|
R 4.7k
3
|
4.7k |
SHUTDOWN (1) >----------*----R4----*----< TxD (3)
|
| 1N4148
*----K|---------< RTS (7) Shutdown
POWER-FAIL (2) >--------------------------< RxD,RI (2,9) On Batt
GROUND (4,9) >--------------------------< GND (5)
</pre>
<p>Operation:</p>
<ul>
<li><p class="first">DTR is "cable power" and must be held at SPACE. DSR or CTS may
be used as a loopback input to determine if the cable is plugged
in.</p>
</li>
<li><p class="first">DCD is the "battery low" signal to the computer. A SPACE on this
line means the battery is low. This is signalled by BATTERY-LOW
being pulled down (it is probably open circuit normally).</p>
<p>Normally, the transistor is turned off, and DCD is held at the MARK
voltage by TxD. When BATTERY-LOW is pulled down, the voltage
divider R2/R1 biases the transistor so that it is turned on,
causing DCD to be pulled up to the SPACE voltage.</p>
</li>
<li><p class="first">TxD must be held at MARK; this is the default state when no data
is being transmitted. This sets the default bias for both DCD and
SHUTDOWN. If this line is an open circuit, then when BATTERY-LOW is
signalled, SHUTDOWN will be automatically signalled; this would be
true if the cable were plugged in to the UPS and not the computer,
or if the computer were turned off.</p>
</li>
<li><p class="first">RTS is the "shutdown" signal from the computer. A SPACE on this
line tells the UPS to shut down.</p>
</li>
<li><p class="first">RxD and RI are both the "power-fail" signals to the computer. A
MARK on this line means the power has failed.</p>
</li>
<li><p class="first">SPACE is a positive voltage, typically +12V. MARK is a negative
voltage, typically -12V. Linux appears to translate SPACE to a 1
and MARK to a 0.</p>
</li>
</ul>
</div>
<div class="section" id="id42">
<h4><a class="toc-backref" href="#id205">940-0095B Cable Wiring</a></h4>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Supported Models:</th><td class="field-body">Many simple-signaling (aka voltage signaling)
models such as BackUPS</td>
</tr>
</tbody>
</table>
<p><em>This diagram is for informational purposes and may not be complete.
We don't recommend that use it to build you build one yourself.</em></p>
<pre class="literal-block">
APC Part# - 940-0095B
Signal Computer UPS
DB9F DB9M
DTR 4 ----*
CTS 8 ----|
DSR 6 ----|
DCD 1 ----*
GND 5 ---------------*---- 4 Ground
|
*---- 9 Common
RI 9 ----*
|
RxD 2 ----*--------------- 2 On Battery
TxD 3 ----------[####]---- 1 Kill UPS Power
4.7K ohm
</pre>
</div>
<div class="section" id="id43">
<h4><a class="toc-backref" href="#id206">940-0119A Cable Wiring</a></h4>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Supported Models:</th><td class="field-body">Older BackUPS Office</td>
</tr>
</tbody>
</table>
<p><em>This diagram is for informational purposes and may not be complete.
We don't recommend that use it to build you build one yourself.</em></p>
<pre class="literal-block">
APC Part# - 940-0119A
UPS Computer
pins pins Signal Signal meaning
1 (brown) 4,6 DSR DTR <- Shutdown when set by computer for 1-5 seconds.
2 (black) 8,9 RI CTS -> On battery power
3 (blue) 1,2 CD RxD -> Low battery
4 (red) 5 Ground
5 (yellow) 7 RTS <- Begin signalling on other pins
6 (none) none
</pre>
</div>
<div class="section" id="serial-backups-es-wiring">
<h4><a class="toc-backref" href="#id207">Serial BackUPS ES Wiring</a></h4>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Supported Models:</th><td class="field-body">Older Serial BackUPS ES</td>
</tr>
<tr class="field"><th class="field-name">Contributed by:</th><td class="field-body">William Stock</td>
</tr>
</tbody>
</table>
<p>The BackUPS ES has a straight through serial cable with no
identification on the plugs. To make it work with apcupsd, specify
the { UPSCABLE 940-0119A} and { UPSTYPE backups}. The equivalent of
cable 940-0119A is done on a PCB inside the unit.</p>
<pre class="literal-block">
computer ----------- BackUPS-ES -----------------
DB9-M DB-9F
pin signal pin
4 DSR -> 4 --+
| diode resistor
6 DTR -> 6 --+---->|----/\/\/\---o kill power
1 DCD <- 1 --+
|
2 RxD <- 2 --+----------------+--o low battery
|
7 RTS -> 7 --------+--/\/\/\--+
|
+--/\/\/\--+
|
8 RI <- 8 --+----------------+--o on battery
|
9 CTS <- 9 --+
5 GND --- 5 ----------------------o ground
3 TxD 3 nc
</pre>
</div>
<div class="section" id="id44">
<h4><a class="toc-backref" href="#id208">940-0128A Cable Wiring</a></h4>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Supported Models:</th><td class="field-body">Older USB BackUPS ES and CS</td>
</tr>
<tr class="field"><th class="field-name">Contributed by:</th><td class="field-body">Many, thanks to all for your help!</td>
</tr>
</tbody>
</table>
<p>Though these UPSes are USB UPSes, APC supplies a serial cable
(typically with a green DB9 F connector) that has 940-0128A stamped
into one side of the plastic serial port connector. The other end
of the cable is a 10 pin RJ45 connector that plugs into the UPS
(thanks to Dean Waldow for sending a cable!). Apcupsd version 3.8.5
and later supports this cable when specified as { UPSCABLE
940-0128A} and { UPSTYPE dumb}. However, running in this mode much
of the information that would be available in USB mode is lost. In
addition, when apcupsd attempts to instruct the UPS to kill the
power, it begins cycling about 4 times a second between battery and
line. The solution to the problem (thanks to Tom Suzda) is to
unplug the UPS and while it is still chattering, press the power
button (on the front of the unit) until the unit beeps and the
chattering stops. After that the UPS should behave normally and
power down 1-2 minutes after requested to do so.</p>
<p>Thanks to all the people who have helped test this and have
provided information on the cable wiring, our best guess for the
cable schematic is the following:</p>
<pre class="literal-block">
APC Part# - 940-0128A
computer --------- Inside the Connector--------- UPS
DB9-F | | RJ45
pin - signal | | Pin - Color
| |
4 DSR ->|---+ |
| | diode resistor |
6 DTR ->|---+---->|----/\/\/\---o kill power | 8 Orange
| |
1 DCD <-|----+ |
| | |
2 RxD <-|----+----------------+--o low battery| 3 Brown
| | |
7 RTS ->|----------+--/\/\/\--+ |
| | |
| +--/\/\/\--+ |
| | |
8 RI <-|----+----------------+--o on battery | 2 Black
| | |
9 CTS <-|----+ |
| signal |
5 GND --|-----------------------o ground | 7 Red
| |
3 TxD | |
| chassis |
Chassis/GND |-----------------------o ground | 4 Black
| |
| Not connected | 1, 5, 6, 9, 10
--------------------------------------
The RJ45 pins are: looking at the end of the connector:
10 9 8 7 6 5 4 3 2 1
_______________________
| . . . . . . . . . . |
| |
-----------------------
|____|
</pre>
</div>
<div class="section" id="d-cable-wiring">
<h4><a class="toc-backref" href="#id209">940-0128D Cable Wiring</a></h4>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Supported Models:</th><td class="field-body">BackUPS XS1000(BX-1000), Possibly other USB models</td>
</tr>
<tr class="field"><th class="field-name">Contributed by:</th><td class="field-body">Jan Babinski jbabinsk at pulsarbeacon dot com</td>
</tr>
</tbody>
</table>
<p>940-0128D is functionally similar to the 940-0128A cable except for
NC on (6) DTR and (2) RD on the computer side.</p>
<p>Unverified: Try setting apcupsd to <tt class="docutils literal">UPSTYPE dumb</tt> and <tt class="docutils literal">UPSCABLE <span class="pre">940-0128A</span></tt>.</p>
<pre class="literal-block">
APC Part# - 940-0128D
DB9(Computer) RJ45-10(UPS)
(5) (1) ____________
( o o o o o ) [ oooooooooo ]
\ o o o o / [____________]
(9) (6) (10) [_] (1)
RI(9)<---+
|
CTS(8)<---+--- E 2N2222(NPN)
\|___
____ /| B |
| C |
| |
+---vvvv---+--[>|------<(2)OnBatt
RTS(7)>---| 2k 1N5819
+---vvvv---+--[>|------<(3)LowBatt
| |
+--- C |
\|___|
/| B
DCD(1)<------- E 2N2222(NPN)
DTR(4)>-------------------------->(8)KillPwr
GND(5)----------------------------(7)Signal GND
(Shield)--------------------------(4)Chassis GND
</pre>
</div>
<div class="section" id="id45">
<h4><a class="toc-backref" href="#id210">940-0127B Cable Wiring</a></h4>
<table class="docutils field-list" frame="void" rules="none">
<col class="field-name" />
<col class="field-body" />
<tbody valign="top">
<tr class="field"><th class="field-name">Supported Models:</th><td class="field-body">BackUPS XS1000(BX-1000), Possibly other USB models</td>
</tr>
<tr class="field"><th class="field-name">Contributed by:</th><td class="field-body">Jan Babinski jbabinsk at pulsarbeacon dot com</td>
</tr>
</tbody>
</table>
<p>Standard USB cable for USB-capable models with 10-pin RJ45 connector.</p>
<pre class="literal-block">
APC Part# - 940-0127B
USB(Computer) RJ45-10(UPS)
_________ ____________
| = = = = | [ oooooooooo ]
|_________| [____________]
(1) (4) (10) [_] (1)
+5V(1)-----------(1)+5V
DATA+(2)-----------(9)DATA+
DATA-(3)-----------(10)DATA-
GND(4)-----------(7)Signal GND
(Shield)-----------(4)Chassis GRND
</pre>
</div>
</div>
<div class="section" id="win32-implementation-restrictions-for-simple-upses">
<h3><a class="toc-backref" href="#id211">Win32 Implementation Restrictions for Simple UPSes</a></h3>
<p>Due to inadequacies in the
Win32 API, it is not possible to set/clear/get all the serial port
line signals. apcupsd can detect: CTS, DSR, RNG, and CD. It can set
and clear: RTS and DTR.</p>
<p>This imposes a few minor restrictions on the functionality of some
of the cables. In particular, LineDown on the Custom Simple cable,
and Low Battery on the 0023A cable are not implemented.</p>
</div>
</div>
<div class="section" id="recalibrating-the-ups-runtime">
<h2><a class="toc-backref" href="#id212">Recalibrating the UPS Runtime</a></h2>
<p>Note: In a future release of apcupsd this procedure will be
replaced by a daemon operation that can be performed on all types
of UPS.</p>
<p>This section does not apply to voltage-signalling or dumb UPSes
such as the older BackUPS models.</p>
<p>Smart UPSes internally compute the remaining runtime, and apcupsd
uses the value supplied by the UPS. As the batteries age (after say
two or three years), the runtime computation may no longer be
accurate since the batteries no longer hold the same charge. As a
consequence, in the event of a power failure, the UPS and thus
apcupsd can report a runtime of 5 minutes remaining when in fact
only one minute remains. This can lead to a shutdown before you
might expect it, because regardless of the runtime remaining that
is reported, the UPS will always correctly detect low batteries and
report it, thus causing apcupsd to correctly shutdown your
computer.</p>
<p>If you wish to have the UPS recalibrate the remaining runtime
calculations, you can do so manually as the current version of
apcupsd does not support this feature. To do so,</p>
<ul class="simple">
<li>Shutdown apcupsd</li>
<li>contact your UPS directly using some terminal program such as
minicom, tip, or cu with the settings 2400 8N1 (2400 baud, 8 bits,
no parity, 1 stop bit). Be extremely careful what you send to your
UPS as certain characters may cause it to power down or may even
cause damage to the UPS. Try sending an upper case <tt class="docutils literal">Y</tt> to the UPS
(without a return at the end). It should respond with <tt class="docutils literal">SM</tt>. If this
is not the case, read the chapter on testing. If you fat finger the
<tt class="docutils literal">Y</tt> and enter <tt class="docutils literal">y</tt> instead, no cause for alarm, you will simply get the
APC copyright notice.</li>
<li>when you are sure you are properly connected send an upper case
D (no cr). This will put the UPS into calibration mode, and it will
drain the battery down to 25% capacity (35% for a Matrix) at which
point it will go back on the mains. In doing so, it will recompute
the runtime calibration.</li>
<li>If you wish to abort the calibration, enter a second D command.</li>
<li>When you are done, restart apcupsd.</li>
</ul>
<p>In principle, you should be able to do this with the computer
powered by the UPS, but if you wish to be completely safe, you
should plug your computer into the wall prior to performing the
runtime calibration. In that case, you will need to artificially
load the UPS with light bulbs or other means. You should supply a
load of about 30 to 35% but not more than 50%. You can determine
the load by looking at the output of the <tt class="docutils literal">apcaccess status</tt>
command while apcupsd is running.</p>
<p>You should not run the recalibration command more than once or
twice per year as discharging these kinds of batteries tends to
shorten their life span.</p>
</div>
<div class="section" id="configuration-directive-reference">
<h2><a class="toc-backref" href="#id213">Configuration Directive Reference</a></h2>
<p>Configuration directives in /etc/apcupsd/apcupsd.conf control the
behavior of the apcupsd daemon. For most installations it is only
necessary to set a handful of general directives. The rest can be
left at their defaults unless you have an exotic configuration.</p>
<p>Note that the apcupsd daemon must be restarted in order for changes to
the configuration file to become active.</p>
<div class="section" id="general-configuration-directives">
<h3><a class="toc-backref" href="#id214">General Configuration Directives</a></h3>
<p>In general, each of these directives is required (except that the
<tt class="docutils literal">DEVICE</tt> directive is ignored for <tt class="docutils literal">UPSCABLE ether</tt> and not required
for <tt class="docutils literal">UPSCABLE usb</tt>).</p>
<dl class="docutils">
<dt><strong>UPSTYPE</strong> <em>driver</em></dt>
<dd>The name of a driver. Should be one of <tt class="docutils literal">dumb</tt>, <tt class="docutils literal">apcsmart</tt>, <tt class="docutils literal">net</tt>,
<tt class="docutils literal">usb</tt>, <tt class="docutils literal">pcnet</tt>, <tt class="docutils literal">snmp</tt>, or <tt class="docutils literal">test</tt>.
This describes your interface type. The UPSTYPE directive can be
defined during installation by using the <tt class="docutils literal"><span class="pre">--with-upstype=</span></tt> option
of the <tt class="docutils literal">configure</tt> program.</dd>
<dt><strong>UPSCABLE</strong> <em>cable</em></dt>
<dd><p class="first">Defines the type of cable connecting the UPS to your computer.</p>
<dl class="docutils">
<dt>Possible generic choices for <cable> are:</dt>
<dd><tt class="docutils literal">simple</tt>, <tt class="docutils literal">smart</tt>, <tt class="docutils literal">ether</tt>, <tt class="docutils literal">usb</tt></dd>
<dt>Or a specific cable model number may be used:</dt>
<dd><tt class="docutils literal"><span class="pre">940-0119A</span></tt>, <tt class="docutils literal"><span class="pre">940-0127A</span></tt>, <tt class="docutils literal"><span class="pre">940-0128A</span></tt>, <tt class="docutils literal"><span class="pre">940-0020B</span></tt>,
<tt class="docutils literal"><span class="pre">940-0020C</span></tt>, <tt class="docutils literal"><span class="pre">940-0023A</span></tt>, <tt class="docutils literal"><span class="pre">940-0024B</span></tt>, <tt class="docutils literal"><span class="pre">940-0024C</span></tt>,
<tt class="docutils literal"><span class="pre">940-1524C</span></tt>, <tt class="docutils literal"><span class="pre">940-0024G</span></tt>, <tt class="docutils literal"><span class="pre">940-0095A</span></tt>, <tt class="docutils literal"><span class="pre">940-0095B</span></tt>,
<tt class="docutils literal"><span class="pre">940-0095C</span></tt>, <tt class="docutils literal"><span class="pre">M-04-02-2000</span></tt></dd>
</dl>
<p class="last">The <tt class="docutils literal"><span class="pre">--with-upscable=</span></tt> option of <tt class="docutils literal">configure</tt> can be used to
set a default for this directive during the your build.</p>
</dd>
<dt><strong>DEVICE</strong> <em>device</em></dt>
<dd><p class="first">Specify which
device is used for UPS communications. For serial ports, it is
usually something like /dev/ttyS0. For USB ports, you may leave the
name of the device blank (no specification) and apcupsd will
automatically search the standard locations for the UPS.</p>
<p>Normally, the <tt class="docutils literal">configure</tt> program will set an appropriate
default value. You may also specify the <tt class="docutils literal"><span class="pre">--with-serial-dev=</span></tt>
option of the <tt class="docutils literal">configure</tt> program to set this directive at build
time.</p>
<p>If you have specified <tt class="docutils literal">UPSTYPE net</tt>, then the device name to be
specified consists of <em>hostname:port</em> where the <em>hostname</em> is the
fully qualified name or IP address of the host (NIS server) and the
<em>port</em> (optional) is the port to use to contact the server.</p>
<p class="last">If you specified <tt class="docutils literal">UPSTYPE snmp</tt>, then the device name becomes
<em>hostname:vendor:community</em>. Please see the <a class="reference internal" href="#support-for-snmp-upses">Support for SNMP UPSes</a>
chapter in this manual for more details.</p>
</dd>
<dt><strong>POLLTIME</strong> <em>time in seconds</em></dt>
<dd>The interval, in seconds, at which apcupsd polls the UPS for status.
This rate is automatically set to 1 second if the UPS goes on
batteries and reset to your specified value when the mains power
returns. This setting applies both to directly-attached UPSes
(<tt class="docutils literal">UPSTYPE</tt> <tt class="docutils literal">apcsmart</tt>, <tt class="docutils literal">usb</tt>, <tt class="docutils literal">dumb</tt>) and networked UPSes
(<tt class="docutils literal">UPSTYPE</tt> <tt class="docutils literal">net</tt>, <tt class="docutils literal">snmp</tt>). Lowering this setting will improve
apcupsd's responsiveness to certain events at the cost of higher CPU
utilization. The default of 60 is appropriate for most situations.
This directive was formerly known as <tt class="docutils literal">NETTIME</tt>.</dd>
<dt><strong>LOCKFILE</strong> <em>path to lockfile</em></dt>
<dd>This option tells apcupsd where to create a lockfile for the USB or
serial port in the specified directory. This is important to keep
two programs from reading or writing the port at the same time.
Please note that although the directive name is LOCKFILE, you are
actually specifying the lock file path. apcupsd automatically
appends the name of the device when creating the file. On most
systems, this directive is automatically set by the <tt class="docutils literal">./configure</tt>
program. You may also explicitly set it during the build process by
using the <tt class="docutils literal"><span class="pre">--with-lock-dir=</span></tt> option of the <tt class="docutils literal">configure</tt> program.</dd>
</dl>
</div>
<div class="section" id="configuration-directives-used-by-the-network-information-server">
<h3><a class="toc-backref" href="#id215">Configuration Directives Used by the Network Information Server</a></h3>
<p>None of these directives are required for proper operation of
apcupsd.</p>
<dl class="docutils">
<dt><strong>NETSERVER</strong> <em>[on | off]</em></dt>
<dd>This configuration directive turns the network information server on or
off. If it is on, apcupsd will spawn a child process that serves
STATUS and EVENTS information over the network. This information is
currently used by the Web-based CGI programs. The default is on. <em>This
option is required to be turned on for net clients and apcaccess to
function.</em></dd>
<dt><strong>NISIP</strong> <em>IP-address</em></dt>
<dd>This directive specifies the
IP address of the network interface on which the NIS server will
listen for incoming connections. Default value is 0.0.0.0 which
means the NIS will listen for connections on all network
interfaces. If your machine has more than one interface, you can
specify the IP of a single interface to limit connections to only
that interface. Furthermore, you can specify the loopback address
(127.0.0.1) to accept connections only from the local machine. You
may also use the <tt class="docutils literal"><span class="pre">--with-nisip=</span></tt> option of the <tt class="docutils literal">configure</tt>
program to set this directive during the build.</dd>
<dt><strong>NISPORT</strong> <em>port</em></dt>
<dd>This configuration directive
specifies the port to be used by the apcupsd Network Information
Server. The default is platform dependent, but typically 3551,
which we have received from IANA as the official apcupsd networking
port. This value should only be changed if it conflicts with an
existing service in use on your network or if you are running multiple
instances of apcupsd on the same machine.</dd>
<dt><strong>EVENTSFILE</strong> <em>filename</em></dt>
<dd><p class="first">If you want the apcupsd network information server to provide the last
10 events via the network, you must specify a file where apcupsd will save
these events. The default is: /etc/apcupsd/apcupsd.events.
Currently, apcupsd will save at most the last 50 events.
Periodically (once an hour by default), apcupsd will check the size
of this file. When more than 50 events are recorded, apcupsd will
truncate the file to the most recent 10 events. Consequently this
file will not grow indefinitely. Although we do not recommend it,
you may change these values by editing apcevents.c and changing the
appropriate defines. Be aware that if you set these values to very
large numbers, apcupsd may make excessive memory demands on the
system during the data access and file truncation operations.</p>
<p class="last">This filename may also be specified at build time by using the
<tt class="docutils literal"><span class="pre">--with-log-dir=</span></tt> option of the <tt class="docutils literal">configure</tt> program.</p>
</dd>
</dl>
</div>
<div class="section" id="configuration-directives-used-during-power-failures">
<h3><a class="toc-backref" href="#id216">Configuration Directives used during Power Failures</a></h3>
<p>In general, none of these
directives are required. However, if you have a voltage-signalling
(dumb) UPS with a cable that does not support the Low Battery
signal, you must set the <tt class="docutils literal">TIMEOUT</tt> directive to force a shutdown.</p>
<dl class="docutils">
<dt><strong>BATTERYLEVEL</strong> <em>percent of battery</em></dt>
<dd>If <tt class="docutils literal">BATTERYLEVEL</tt> is specified, during a power failure, apcupsd
will halt the system when the remaining battery charge falls below
the specified percentage. The default is 5 percent. This directive
is ignored for dumb (voltage-signalling) UPSes. To totally disable
this counter, set <tt class="docutils literal">BATTERYLEVEL <span class="pre">-1</span></tt> in your apcupsd.conf file.</dd>
<dt><strong>MINUTES</strong> <em>battery runtime in minutes</em></dt>
<dd>If <tt class="docutils literal">MINUTES</tt> is specified, during a power failure, apcupsd
will shutdown the system when the remaining runtime on batteries as
internally calculated by the UPS falls below the time specified.
The default is 3. This directive is ignored for dumb
(voltage-signalling) UPSes. It should be noted that some UPSes
report an incorrect value for remaining runtime when the battery is
fully charged. This can be checked by examining the <tt class="docutils literal">TIMELEFT</tt>
value as printed in the output of an '<tt class="docutils literal">apcaccess status</tt>' command.
If the value is zero or otherwise unreasonable, your UPS is
probably broken. In this case, we recommend that you disable this
timer by setting <tt class="docutils literal">MINUTES <span class="pre">-1</span></tt> in your apcupsd.conf file.</dd>
<dt><strong>TIMEOUT</strong> <em>time in seconds</em></dt>
<dd>After a power
failure, apcupsd will halt the system when <tt class="docutils literal">TIMEOUT</tt> seconds have
expired. A value of zero disables this timer. Normally for all
Smart UPS models and dumb UPSes with cables that support low
battery detection, this should be zero so that the shutdown time
will be determined by the battery level and/or remaining runtime
(see above) or in the case of a voltage-signalling UPS, when the
battery is exhausted. This command is required for dumb UPSes that
do not provide a battery exhausted signal (only testing can
determine this point). For more information, see the
<a class="reference internal" href="#testing-apcupsd">Testing Apcupsd</a> section of this manual. This
timer can also be useful if you want some slave machines to
shutdown before other machines to conserve battery power. It is
also useful for testing apcupsd because you can force a rapid
shutdown by setting a small value (e.g. 60) and pulling the plug to
the UPS.</dd>
</dl>
<p><tt class="docutils literal">TIMEOUT</tt>, <tt class="docutils literal">BATTERYLEVEL</tt>, and <tt class="docutils literal">MINUTES</tt> can be set together
without problems. apcupsd will react to the first case or test that
is valid. Normally SmartUPS users will set <tt class="docutils literal">TIMEOUT</tt> to zero so
that the system is shutdown depending on the percentage battery
charge remaining (<tt class="docutils literal">BATTERYLEVEL</tt>) or the remaining battery runtime
(<tt class="docutils literal">MINUTES</tt>).</p>
<dl class="docutils">
<dt><strong>ANNOY</strong> <em>time in seconds</em></dt>
<dd><p class="first">Specify the time
in seconds between messages requesting logged in users to get off
the system during a power failure. This timer starts only when the
UPS is running on batteries. The default is 300 seconds (5
minutes). apcupsd sends the annoy messages by invoking the
apccontrol script with the <tt class="docutils literal">annoyme</tt> argument. The default is to
send a wall message on Unix systems and a popup message in
Windows.</p>
<p>The value of <tt class="docutils literal">ANNOYDELAY</tt> must be greater than the value of
<tt class="docutils literal">ANNOY</tt> in order to receive annoy messages (this doesn't make sense,
and means that the default values do not generate annoy messages:
KES).</p>
<p class="last">Note that if <tt class="docutils literal">NOLOGON disable</tt> is set, the annoy messages
will also be disabled.</p>
</dd>
<dt><strong>ANNOYDELAY</strong> <em>time in seconds</em></dt>
<dd>Specify delay time in seconds before apcupsd begins requesting logged in
users to get off the system during a power failure. This timer
starts only after the UPS is running on batteries. This timer is
reset when the power returns. The default is 60 seconds. Thus, the
first warning to log off the system occurs after 60 seconds on
batteries, assuming that <tt class="docutils literal">NOLOGON</tt> is not set to <tt class="docutils literal">disable</tt>.</dd>
<dt><strong>NOLOGON</strong> <em>disable</em> | <em>timeout</em> | <em>percent</em> | <em>minutes</em> | <em>always</em></dt>
<dd><p class="first">Specifies when apcupsd should prevent user logins</p>
<p>The type specified allows you define the point when apcupsd will
create the 'nologin' file and thus when user logins are prohibited.
Once the 'nologin' file is created, normal users are prevented from
logging in. Control of when this file is created is important for
allowing systems with big UPSes to run as normally until the system
administrator determines the need for preventing user logins. The
feature also allows the system administrator to hold the "ANNOY"
factor until the 'nologin' file is created. The default is always
disable if no <tt class="docutils literal">NOLOGON</tt> directive is specified.</p>
<p>The 'nologin' file will be created in the directory specified by
the <tt class="docutils literal">NOLOGINDIR</tt> directive described below.</p>
<p>As far as I can tell, the only useful types are disable and always
since the difference in the time when the logout warning is given
and shutdown occurs for the other types is very short (KES).</p>
<blockquote class="last">
<p><em>disable</em> prevents apcupsd from creating the nologin
file. Consequently, any user can login during a power failure
condition. Also, the ANNOY feature is disabled so users will not be
warned to logoff the system.</p>
<p><em>timeout</em> specifies that apcupsd should prohibit logins
after the UPS is on batteries for 90% of the time specified on the
<tt class="docutils literal">TIMEOUT</tt> configuration directive. Note! Normally you don't want
to specify a TIMEOUT value, so this option is probably not too
useful (KES).</p>
<p><em>percent</em> specifies that apcupsd should prohibit logins
when the remaining battery charge percentage reaches 110% or less
than the value specified on the <tt class="docutils literal">BATTERYLEVEL</tt> configuration
directive. Thus if the <tt class="docutils literal">BATTERYLEVEL</tt> is specified as 15, apcupsd
will prohibit logins when the battery charge drops below 16% (15% X
110% = 16%).</p>
<p><em>minutes</em> specifies that apcupsd should prohibit logins
when the remaining runtime in minutes reaches 110% or less than the
value specified on the <tt class="docutils literal">MINUTES</tt> configuration directive. Thus if
<tt class="docutils literal">MINUTES</tt> is set to 3, apcupsd will prohibit logins when the
remaining runtime is less than 3 minutes (3 X 110% = 3).</p>
<p><em>always</em> causes apcupsd to immediately prohibit logins
when a power failure occurs. This will also enable the ANNOY
feature.</p>
</blockquote>
</dd>
<dt><strong>NOLOGINDIR</strong> <em>path to nologin dir</em></dt>
<dd><p class="first">This directive configures the directory into which apcupsd will
write the nologin file, as described above for the <tt class="docutils literal">NOLOGON</tt>
directive.</p>
<p class="last">Normally, the <tt class="docutils literal">configure</tt> program will set an appropriate
default value for your platform, often /etc. You may also specify
the <tt class="docutils literal"><span class="pre">--with-nologdir=</span></tt> option of the <tt class="docutils literal">configure</tt> program to
change the default at compile time.</p>
</dd>
<dt><strong>KILLDELAY</strong> <em>time in seconds</em></dt>
<dd>If <tt class="docutils literal">KILLDELAY</tt> is set, apcupsd will continue running after a shutdown
has been requested, and after the specified time in seconds,
apcupsd will attempt to shut off the UPS the power. This directive
should normally be disabled by setting the value to zero, but on
some systems such as Win32 systems apcupsd cannot regain control
after a shutdown to force the UPS to shut off the power. In this
case, with proper consideration for the timing, the <tt class="docutils literal">KILLDELAY</tt>
directive can be useful. Please be aware, if you cause apcupsd to
kill the power to your computer too early, the system and the disks
may not have been properly prepared. In addition, apcupsd must
continue running after the shutdown is requested, and on Unix
systems, this is not normally the case as the system will terminate
all processes during the shutdown.</dd>
<dt><strong>SCRIPTDIR</strong> <em>path to apccontrol dir</em></dt>
<dd><p class="first">This option configures the directory in which apccontrol and
other event scripts are located.</p>
<p class="last">Normally, the <tt class="docutils literal">configure</tt> program will set an appropriate
default value for your platform, often /etc/apcupsd.</p>
</dd>
<dt><strong>PWRFAILDIR</strong> <em>path to powerfail dir</em></dt>
<dd><p class="first">When apcupsd shuts down your system, it creates a temporary
"flag file" which is used by the operating system halt scripts to
know if this shutdown is due to a power failure. This directive
configures which directory the flag file will be written into. The
chosen directory must be writable by the user apcupsd is running as
(normally root) and must not be cleared or unmounted early in the
shutdown sequence.</p>
<p class="last">Normally, the <tt class="docutils literal">configure</tt> program will set an appropriate
default value for your platform, often /etc/apcupsd. You may also
specify the <tt class="docutils literal"><span class="pre">--with-pwrfaildir=</span></tt> option of the <tt class="docutils literal">configure</tt>
program to change the default at compile time.</p>
</dd>
</dl>
</div>
<div class="section" id="configuration-directives-used-to-control-system-logging">
<h3><a class="toc-backref" href="#id217">Configuration Directives used to Control System Logging</a></h3>
<dl class="docutils">
<dt><strong>STATTIME</strong> <em>time in seconds</em></dt>
<dd>This directive supplies the time
interval in seconds between writes to the STATUS file. If set to zero, the
STATUS file will not be written. Please note that in a future
version of apcupsd the STATUS file code will disappear since its
functionality has been replaced by the Network Information Server
and by <tt class="docutils literal">apcaccess status</tt>, as a consequence, it is normally
disabled by setting it to zero.</dd>
<dt><strong>STATFILE</strong> <em>file</em></dt>
<dd>This directive specifies the file
to be used when writing the STATUS information. The default is
/etc/apcupsd/apcupsd.status.</dd>
<dt><strong>DATATIME</strong> <em>time in seconds</em></dt>
<dd>This directives supplies the time
interval in seconds between writes of PowerChute-like data information to
the log file. See the <a class="reference internal" href="#data-logging">DATA Logging</a> section of this manual for
additional details.</dd>
<dt><strong>FACILITY</strong> <em>log-facility</em></dt>
<dd>The <tt class="docutils literal">FACILITY</tt>
directive can be used to change the system logging class or
facility. The default is <tt class="docutils literal">DAEMON</tt>. This parameter can be useful if
you wish to direct the apcupsd system logging information to other
than your system default files. See the <a class="reference internal" href="#apcupsd-system-logging">apcupsd System Logging</a>
section of this manual for additional details.</dd>
</dl>
</div>
<div class="section" id="configuration-directives-for-sharing-a-ups">
<h3><a class="toc-backref" href="#id218">Configuration Directives for Sharing a UPS</a></h3>
<p>The following directives apply to sharing an UPS using a ShareUPS
hardware module. Most users will not use this mode.</p>
<p><strong>UPSCLASS</strong> <em>standalone</em> | <em>shareslave</em> | <em>sharemaster</em></p>
<blockquote>
<p>The default is <tt class="docutils literal">standalone</tt> and should be used for all machines
powered by the UPS and having a serial port or other direct
connection to the UPS. This is the normal case.</p>
<p>Use <tt class="docutils literal">shareslave</tt> if and only if you are using a ShareUPS and
connected to a BASIC Port with Simple Signal. This code is not
fully tested.</p>
<p>Use <tt class="docutils literal">sharemaster</tt>, if and only if you are using a ShareUPS and
connected to the ADVANCED Port Smart Signal control. This code is
not fully tested.</p>
</blockquote>
<p><strong>UPSMODE</strong> <em>disable</em> | <em>share</em></p>
<blockquote>
<p>For normal standalone operations, you will set <tt class="docutils literal">UPSMODE disable</tt>
to indicate that you are disabling the ShareUPS support.</p>
<p>Use <tt class="docutils literal">share</tt> for two or seven additional simple signal ports on
a SmartAccessories(tm) (internal/external box) for SmartUPSes. The
share and sharenet code is not fully tested.</p>
</blockquote>
</div>
<div class="section" id="configuration-directives-used-to-set-the-ups-eeprom">
<h3><a class="toc-backref" href="#id219">Configuration Directives Used to Set the UPS EEPROM</a></h3>
<p><em>These directives have no effect on the operation of apcupsd but are
reserved for use by apctest when bulk programming the values of the
UPS EEPROM configuration variables in a Smart-UPS model.</em></p>
<p><strong>UPSNAME</strong> <em><string></em></p>
<blockquote>
Name of UPS. Maximum of 8 characters.</blockquote>
<p><strong>BATTDATE</strong> [ <em>mm/dd/yy</em> | <em>dd/mm/yy</em> ]</p>
<blockquote>
Last battery replacement date. Maximum of 8 characters.</blockquote>
<p><strong>SENSITIVITY</strong> [ <em>H</em> | <em>M</em> | <em>L</em> ]</p>
<blockquote>
H : High (most sensitive setting)
M : Medium
L : Low (least sensitive setting)</blockquote>
<p><strong>WAKEUP</strong> [ <em>000</em> | <em>060</em> | <em>180</em> | <em>300</em> ]</p>
<blockquote>
The time delay in seconds that the UPS waits after the return of utility
power before "waking up" and restoring power to the connected equipment.</blockquote>
<p><strong>SLEEP</strong> [ <em>020</em> | <em>180</em> | <em>300</em> | <em>600</em> ]</p>
<blockquote>
The time delay in seconds for which the UPS waits or "sleeps" after it
receives a request to power off the connected system.</blockquote>
<p><strong>LOTRANSFER</strong> <em><voltage></em></p>
<blockquote>
<p>Low line voltage causing transfer to battery power or activation of
SmartBoost. Allowable values depend on the last letter of the firmware
or APCMODEL. Typical values are:</p>
<pre class="literal-block">
D 106 103 100 097
M 177 172 168 182
A 092 090 088 086
I 208 204 200 196
</pre>
<p>where D = domestic (USA), M = Canada, A = Asia and I = International.</p>
</blockquote>
<p><strong>HITRANSFER</strong> <em><voltage></em></p>
<blockquote>
<p>High line voltage causing transfer to battery power or activation of
SmartTrim. Allowable values depend on the last letter of the firmware
or APCMODEL. Typical values are:</p>
<pre class="literal-block">
D 127 130 133 136
M 229 234 239 224
A 108 110 112 114
I 253 257 261 265
</pre>
<p>where D = domestic (USA), M = Canada, A = Asia and I = International.</p>
</blockquote>
<p><strong>RETURNCHARGE</strong> [ <em>00</em> | <em>15</em> | <em>50</em> | <em>90</em> ]</p>
<blockquote>
Percentage of battery charge needed for the UPS to restore power to the
connected equipment.</blockquote>
<p><strong>BEEPSTATE</strong> [ <em>0</em> | <em>T</em> | <em>L</em> | <em>N</em> ]</p>
<blockquote>
<p>Alarm delay.</p>
<pre class="literal-block">
0 : Zero delay after power fails.
T : When power fails plus 30 seconds.
L : When low battery occurs.
N : Never.
</pre>
</blockquote>
<p><strong>LOWBATT</strong> <em><minutes></em></p>
<blockquote>
Low battery warning occurs when the specified number of minutes remains
before the UPS estimates battery power will be exhausted. There are four
user-changeable settings: 2, 5, 7, or 10 minutes</blockquote>
<p><strong>OUTPUTVOLTS</strong> <em><voltage></em></p>
<blockquote>
<p>UPS nominal output voltage when running on battery. Allowable values
depend on the last letter of the firmware or APCMODEL. Typical values are:</p>
<pre class="literal-block">
D 115
M 208
A 100
I 230 240 220 225
</pre>
<p>where D = domestic (USA), M = Canada, A = Asia and I = International.</p>
</blockquote>
<p><strong>SELFTEST</strong> [ <em>336</em> | <em>168</em> | <em>ON</em> | <em>OFF</em> ]</p>
<blockquote>
Self test interval in hours (336 = 2 weeks, 168 = 1 week,
ON = at power on, OFF = never).</blockquote>
</div>
</div>
<div class="section" id="apcupsd-status-logging">
<h2><a class="toc-backref" href="#id220">apcupsd Status Logging</a></h2>
<p>There is a good deal of information available about the UPS and apcupsd's
status. This document describes the format of that information.
Normally you will get at it via <tt class="docutils literal">apcaccess</tt>, but there are other ways
as well.</p>
<div class="section" id="status-report-format">
<h3><a class="toc-backref" href="#id221">Status report format</a></h3>
<p>STATUS output is in ASCII format with a single data value or piece
of information on each line output. Because not all UPSes supply
the same information, the output varies based on the type of UPS
that you are using. In general, if the information is not available
for your UPS, the line will be missing entirely or the data portion of
the output record will contain an <tt class="docutils literal">N/A</tt> indicating that the information
is not available.</p>
<p>Status logging consists of periodically logging ALL available
information concerning the UPS. Since the volume of data is rather
large (over 1000 bytes per status), the STATUS data is not
automatically sent to the system log file. Instead, it is written
as a series of data records in a specific file (normally
/etc/apcupsd/apcupsd.status).</p>
<p>After each write, the file is rewound so that the size of the file
remains constant. The STATUS file is kept for backward compatibility
and will be eliminated in a future version of apcupsd. The preferred
method for obtaining this information is from apcaccess or by using
the CGI interface (see <a class="reference internal" href="#apcupsd-network-monitoring-cgi-programs">apcupsd Network Monitoring (CGI) Programs</a>).</p>
<p>To make reading the status data reliable via a named pipe, the
first record written contains a version number, the number of
records that follow the first record, and the total number of bytes
in those subsequent records. An actual example of such a status
file (/etc/apcupsd/apcupsd.status) is shown below.</p>
<p>Consequently, the first record always consists of 24 bytes (23
characters followed by a newline). This record starts with APC and
as indicated in the example is followed by 37 records
consisting of 906 bytes. The last record begins with END APC and
contains the date and time matching the DATE record.</p>
<p>When this data is written to a file, it is written as two records,
the first record, and all the other records together. In reading
the file, it can be either be read a record at a time, or in one
big read.</p>
<p>When this data is written to syslog(), it is written a record at a
time. The first record is the first 24 bytes. By having the number
of records and the size in the first record, the complete status
can be reliably reassembled.</p>
</div>
<div class="section" id="status-report-example">
<h3><a class="toc-backref" href="#id222">Status Report Example</a></h3>
<p>An example of output from a BackUPS RS 1500 follows:</p>
<pre class="literal-block">
APC : 001,037,0906
DATE : Sun Apr 26 17:22:22 EDT 2009
HOSTNAME : mail.kroptech.com
VERSION : 3.14.2 (10 September 2007) redhat
UPSNAME : ups0
CABLE : USB Cable
MODEL : Back-UPS RS 1500
UPSMODE : Stand Alone
STARTTIME: Sun Apr 26 10:22:46 EDT 2009
STATUS : ONLINE
LINEV : 123.0 Volts
LOADPCT : 24.0 Percent Load Capacity
BCHARGE : 100.0 Percent
TIMELEFT : 144.5 Minutes
MBATTCHG : 5 Percent
MINTIMEL : 3 Minutes
MAXTIME : 0 Seconds
SENSE : Medium
LOTRANS : 097.0 Volts
HITRANS : 138.0 Volts
ALARMDEL : Always
BATTV : 26.8 Volts
LASTXFER : Low line voltage
NUMXFERS : 0
TONBATT : 0 seconds
CUMONBATT: 0 seconds
XOFFBATT : N/A
SELFTEST : NO
STATFLAG : 0x07000008 Status Flag
MANDATE : 2003-05-08
SERIALNO : JB0319033692
BATTDATE : 2001-09-25
NOMINV : 120
NOMBATTV : 24.0
FIRMWARE : 8.g6 .D USB FW:g6
APCMODEL : Back-UPS RS 1500
END APC : Sun Apr 26 17:22:32 EDT 2009
</pre>
</div>
<div class="section" id="status-report-fields">
<h3><a class="toc-backref" href="#id223">Status Report Fields</a></h3>
<p>The meaning of the above variables are:</p>
<dl class="docutils">
<dt><strong>APC</strong></dt>
<dd>Header record indicating the STATUS format
revision level, the number of records that follow the APC
statement, and the number of bytes that follow the record.</dd>
<dt><strong>DATE</strong></dt>
<dd>The date and time that the information was last obtained from the UPS.</dd>
<dt><strong>HOSTNAME</strong></dt>
<dd>The name of the machine that collected the UPS data.</dd>
<dt><strong>UPSNAME</strong></dt>
<dd>The name of the UPS as stored in the EEPROM or in the <tt class="docutils literal">UPSNAME</tt>
directive in the configuration file.</dd>
<dt><strong>VERSION</strong></dt>
<dd>The apcupsd release number, build date, and platform.</dd>
<dt><strong>CABLE</strong></dt>
<dd>The cable as specified in the configuration file (<tt class="docutils literal">UPSCABLE</tt>).</dd>
<dt><strong>MODEL</strong></dt>
<dd>The UPS model as derived from information from the UPS.</dd>
<dt><strong>UPSMODE</strong></dt>
<dd>The mode in which apcupsd is operating as specified in the configuration
file (<tt class="docutils literal">UPSMODE</tt>)</dd>
<dt><strong>STARTTIME</strong></dt>
<dd>The time/date that apcupsd was started.</dd>
<dt><strong>STATUS</strong></dt>
<dd>The current status of the UPS (ONLINE, ONBATT, etc.)</dd>
<dt><strong>LINEV</strong></dt>
<dd>The current line voltage as returned by the UPS.</dd>
<dt><strong>LOADPCT</strong></dt>
<dd>The percentage of load capacity as estimated by the UPS.</dd>
<dt><strong>BCHARGE</strong></dt>
<dd>The percentage charge on the batteries.</dd>
<dt><strong>TIMELEFT</strong></dt>
<dd>The remaining runtime left on batteries as estimated by the UPS.</dd>
<dt><strong>MBATTCHG</strong></dt>
<dd>If the battery charge percentage (BCHARGE)
drops below this value, apcupsd will shutdown your system.
Value is set in the configuration file (<tt class="docutils literal">BATTERYLEVEL</tt>)</dd>
<dt><strong>MINTIMEL</strong></dt>
<dd>apcupsd will shutdown your system if the
remaining runtime equals or is below this point.
Value is set in the configuration file (<tt class="docutils literal">MINUTES</tt>)</dd>
<dt><strong>MAXTIME</strong></dt>
<dd>apcupsd will shutdown your system if the time
on batteries exceeds this value. A value of zero disables the
feature. Value is set in the configuration file (<tt class="docutils literal">TIMEOUT</tt>)</dd>
<dt><strong>MAXLINEV</strong></dt>
<dd>The maximum line voltage since the UPS was started, as reported by the UPS</dd>
<dt><strong>MINLINEV</strong></dt>
<dd>The minimum line voltage since the UPS was started, as returned by the UPS</dd>
<dt><strong>OUTPUTV</strong></dt>
<dd>The voltage the UPS is supplying to your equipment</dd>
<dt><strong>SENSE</strong></dt>
<dd>The sensitivity level of the UPS to line voltage fluctuations.</dd>
<dt><strong>DWAKE</strong></dt>
<dd>The amount of time the UPS will wait before restoring power to your
equipment after a power off condition when the power is restored.</dd>
<dt><strong>DSHUTD</strong></dt>
<dd>The grace delay that the UPS gives after
receiving a power down command from apcupsd before it powers off
your equipment.</dd>
<dt><strong>DLOWBATT</strong></dt>
<dd>The remaining runtime below which the UPS
sends the low battery signal. At this point apcupsd will force an
immediate emergency shutdown.</dd>
<dt><strong>LOTRANS</strong></dt>
<dd>The line voltage below which the UPS will switch to batteries.</dd>
<dt><strong>HITRANS</strong></dt>
<dd>The line voltage above which the UPS will switch to batteries.</dd>
<dt><strong>RETPCT</strong></dt>
<dd>The percentage charge that the batteries must
have after a power off condition before the UPS will restore power
to your equipment.</dd>
<dt><strong>ITEMP</strong></dt>
<dd>Internal UPS temperature as supplied by the UPS.</dd>
<dt><strong>ALARMDEL</strong></dt>
<dd>The delay period for the UPS alarm.</dd>
<dt><strong>BATTV</strong></dt>
<dd>Battery voltage as supplied by the UPS.</dd>
<dt><strong>LINEFREQ</strong></dt>
<dd>Line frequency in hertz as given by the UPS.</dd>
<dt><strong>LASTXFER</strong></dt>
<dd>The reason for the last transfer to batteries.</dd>
<dt><strong>NUMXFERS</strong></dt>
<dd>The number of transfers to batteries since apcupsd startup.</dd>
<dt><strong>XONBATT</strong></dt>
<dd>Time and date of last transfer to batteries, or N/A.</dd>
<dt><strong>TONBATT</strong></dt>
<dd>Time in seconds currently on batteries, or 0.</dd>
<dt><strong>CUMONBATT</strong></dt>
<dd>Total (cumulative) time on batteries in seconds since apcupsd startup.</dd>
<dt><strong>XOFFBATT</strong></dt>
<dd>Time and date of last transfer from batteries, or N/A.</dd>
<dt><strong>SELFTEST</strong></dt>
<dd><p class="first">The results of the last self test, and may have the following values:</p>
<ul class="last simple">
<li>OK: self test indicates good battery</li>
<li>BT: self test failed due to insufficient battery capacity</li>
<li>NG: self test failed due to overload</li>
<li>NO: No results (i.e. no self test performed in the last 5 minutes)</li>
</ul>
</dd>
<dt><strong>STESTI</strong></dt>
<dd>The interval in hours between automatic self tests.</dd>
<dt><strong>STATFLAG</strong></dt>
<dd>Status flag. English version is given by STATUS.</dd>
<dt><strong>DIPSW</strong></dt>
<dd>The current dip switch settings on UPSes that have them.</dd>
<dt><strong>REG1</strong></dt>
<dd>The value from the UPS fault register 1.</dd>
<dt><strong>REG2</strong></dt>
<dd>The value from the UPS fault register 2.</dd>
<dt><strong>REG3</strong></dt>
<dd>The value from the UPS fault register 3.</dd>
<dt><strong>MANDATE</strong></dt>
<dd>The date the UPS was manufactured.</dd>
<dt><strong>SERIALNO</strong></dt>
<dd>The UPS serial number.</dd>
<dt><strong>BATTDATE</strong></dt>
<dd>The date that batteries were last replaced.</dd>
<dt><strong>NOMOUTV</strong></dt>
<dd>The output voltage that the UPS will attempt to supply when on battery
power.</dd>
<dt><strong>NOMINV</strong></dt>
<dd>The input voltage that the UPS is configured to expect.</dd>
<dt><strong>NOMBATTV</strong></dt>
<dd>The nominal battery voltage.</dd>
<dt><strong>NOMPOWER</strong></dt>
<dd>The maximum power in Watts that the UPS is designed to supply.</dd>
<dt><strong>HUMIDITY</strong></dt>
<dd>The humidity as measured by the UPS.</dd>
<dt><strong>AMBTEMP</strong></dt>
<dd>The ambient temperature as measured by the UPS.</dd>
<dt><strong>EXTBATTS</strong></dt>
<dd>The number of external batteries as
defined by the user. A correct number here helps the UPS compute
the remaining runtime more accurately.</dd>
<dt><strong>BADBATTS</strong></dt>
<dd>The number of bad battery packs.</dd>
<dt><strong>FIRMWARE</strong></dt>
<dd>The firmware revision number as reported by the UPS.</dd>
<dt><strong>APCMODEL</strong></dt>
<dd>The old APC model identification code.</dd>
<dt><strong>END APC</strong></dt>
<dd>The time and date that the STATUS record was written.</dd>
</dl>
</div>
<div class="section" id="logging-the-status-information">
<h3><a class="toc-backref" href="#id224">Logging the STATUS Information</a></h3>
<p>If specified in the configuration file, the STATUS data will also be
written to the system log file. Please note, that it would not
normally be wise to write this data to a normal system log file as
there is no mechanism in syslog() to rewind the file and hence the
log file would quickly become enormous. However, in two cases, it
can be very useful to use syslog() to write this information.</p>
<p>The first case is to set up your syslog.conf file so that the data
is written to a named pipe. In this case, normally not more than
about 8192 bytes of data will be kept before it is discarded by the
system.</p>
<p>The second case is to setup your syslog.conf file so that the
status data is sent to another machine, which presumably then
writes it to a named pipe. Consequently, with this mechanism,
provides a simple means of networking apcupsd STATUS information.</p>
<p>Although we mention system logging of STATUS information, we
strongly recommend that you use apcaccess or the CGI interface to
get this information.</p>
</div>
</div>
<div class="section" id="the-shutdown-sequence-and-its-discontents">
<h2><a class="toc-backref" href="#id225">The Shutdown Sequence and its Discontents</a></h2>
<div class="section" id="shutdown-sequence">
<h3><a class="toc-backref" href="#id226">Shutdown Sequence</a></h3>
<p>If you experienced so problems with the testing procedures, or if
you are porting apcupsd to another system, or you are simply
curious, you may want to know exactly what is going on during the
shutdown process.</p>
<p>The shutdown sequence is as follows:</p>
<ul>
<li><p class="first">apcupsd detects that there is a power problem and it calls
<tt class="docutils literal">/etc/apcupsd/apccontrol powerout</tt>. By default this event
does nothing, but it can be overridden to notify users, etc.</p>
</li>
<li><p class="first">After the configured <tt class="docutils literal">ONBATTERYDELAY</tt>, apcupsd
calls <tt class="docutils literal">/etc/apcupsd/apccontrol onbattery</tt>, which normally sends a
message to all users informing them that the UPS is on batteries.</p>
</li>
<li><p class="first">When one of the conditions listed below occurs, apcupsd issues a
shutdown command by calling <tt class="docutils literal">/etc/apcupsd/apccontrol doshutdown</tt>,
which should perform a shutdown of your system using the system
shutdown(8) command. You can modify the behavior as described in
<a class="reference internal" href="#customizing-event-handling">Customizing Event Handling</a>.</p>
<p>The conditions that trigger the shutdown can be any of the following:</p>
<ul class="simple">
<li>Running time on batteries have expired (<tt class="docutils literal">TIMEOUT</tt>)</li>
<li>The battery runtime remaining is below the configured value (<tt class="docutils literal">BATTERYLEVEL</tt>)</li>
<li>The estimated remaining runtime is below the configured value (<tt class="docutils literal">MINUTES</tt>)</li>
<li>The UPS signals that the batteries are exhausted.</li>
</ul>
<p>A shutdown could also be initiated if apcupsd detects that the
batteries are no longer functioning correctly. This case, though
very unusual, can happen at any time even if there is proper mains
voltage, and <tt class="docutils literal">/etc/apcupsd/apccontrol emergency</tt> is called.</p>
<p>Just before initiating any shutdown through the apccontrol script,
apcupsd will create the file /etc/apcupsd/powerfail. This file will
be used later in the shutdown sequence to recall apcupsd after
syncing of the disks to initiate a power off of the UPS.</p>
<p>If the /etc/nologin file has not already been created, it will
normally be created during the shutdown sequence to prevent
additional users from logging in (see the <tt class="docutils literal">NOLOGIN</tt> configuration
directive).</p>
<p>Even though apcupsd has requested the system to perform a shutdown,
it continues running.</p>
</li>
<li><p class="first">When the system signals apcupsd to do exit, it does so. This is
part of the normal system shutdown (at least on Unix and Linux
systems) and the exact time that apcupsd receives the termination
signal depends on how the shutdown links (usually in /etc/rc.d) are
set.</p>
<p>Note that on Windows NT systems, apcupsd apparently continues to
run as a Service even though the machine is "shutdown".</p>
</li>
<li><p class="first">During the shutdown of the system after apcupsd has been forced
to exit, one of the last things done by the system shutdown is to
call the halt script, which is usually in /etc/rc.d/halt or
/etc/rc.d/init.d/halt, or possibly in /sbin/init.d/rc.0 depending
on your system. If apcupsd was properly installed, this standard
halt script was modified to include a bit of new logic just before
the final halt of the system. It first tests if the file
/etc/apcupsd/powerfail exists, and if it does, it executes
<tt class="docutils literal">/etc/apcupsd/apccontrol killpower</tt>. It is this last step that will
cause apcupsd to be re-executed with the <tt class="docutils literal"><span class="pre">--killpower</span></tt> option
on the command line. This option tells apcupsd to inform the UPS to
kill the power.</p>
</li>
</ul>
<p>This final step is important if you want to ensure that your system
will automatically reboot when the power comes back on. The actual
code used on the Red Hat version is:</p>
<blockquote>
<pre class="literal-block">
# See if this is a powerfail situation. # ***apcupsd***
if [ -f /etc/apcupsd/powerfail ]; then # ***apcupsd***
echo # ***apcupsd***
echo "APCUPSD will now power off the UPS" # ***apcupsd***
echo # ***apcupsd***
/etc/apcupsd/apccontrol killpower # ***apcupsd***
echo # ***apcupsd***
echo "Please ensure that the UPS has powered off before rebooting" # ***apcupsd***
echo "Otherwise, the UPS may cut the power during the reboot!!!" # ***apcupsd***
echo # ***apcupsd***
fi # ***apcupsd***
</pre>
</blockquote>
<p>The above code must be inserted as late as possible in the halt
script. On many systems, such as Red Hat, all the disk drives were
unmounted, then remounted read-only, thus permitting access to the
/etc files and the apcupsd executable. If your system does not
explicitly remount the disks, you must remount them in read-only
mode in the code that you add. Examples of code fragments that do
this can be found in the distributions/suse subdirectory of the
source.</p>
<p>If you are not able to insert the above code in your halt script
because there is no halt script, or because your halt script calls
the init program as some Unix systems do, you can either just
forget about powering off the UPS, which means that your machine
will not automatically reboot after a power failure, or there is
yet another alternative, though not at all as satisfying as
inserting code in the halt script.</p>
<p>Only if you cannot insert the appropriate code in the halt script,
when you start apcupsd, normally from the /etc/rc.d/init.d/apcupsd
script, use the <tt class="docutils literal"><span class="pre">--kill-on-powerfail</span></tt> option. This will cause
apcupsd to program the UPS to shutoff the power just before it
(apcupsd) does the system shutdown. Please note that this is not
the most ideal solution. Read on to understand why.</p>
<p>A very important consideration is that you must set the EEPROM in
your UPS so that it waits a sufficient time for the system to halt
before it shuts off the UPS power.</p>
<p>When using a USB connection, apcupsd automatically sets this value
to 60 seconds. When using a serial connection to a SmartUPS, you
must configure the value in the UPS EEPROM by hand using <tt class="docutils literal">apctest</tt>.</p>
</div>
<div class="section" id="shutdown-problems">
<h3><a class="toc-backref" href="#id227">Shutdown Problems</a></h3>
<p>Obviously if your halt script is not properly modified, apcupsd
will not be able to shut off the power to the UPS, and if the power
returns before the batteries are exhausted your system will not
automatically reboot. In any case, your machine should have been
cleanly shut down.</p>
</div>
<div class="section" id="master-slave-shutdown">
<h3><a class="toc-backref" href="#id228">Master/Slave Shutdown</a></h3>
<p>In master/slave configurations, however, the master cannot be 100
percent sure that the slaves have all shutdown before it performs
the power off. To avoid this situation, be sure to configure any
slaves (clients) to shut down before the master by setting different
<tt class="docutils literal">TIMEOUT</tt>, <tt class="docutils literal">BATTERYLEVEL</tt>, or <tt class="docutils literal">MINUTES</tt> parameters in the
config file.</p>
<p>Also, on a slave machine, you do not want to use the modified halt
script since it will recall apcupsd, which will detect that it is a
slave (i.e. no connection to the UPS) and will complain that it
cannot do the killpower. This situation is not harmful just
annoying and possibly confusing.</p>
<p>One possible problem during shutdown can be caused by remnants of
old versions. Please be sure to delete or rename all prior versions
(/usr/local/sbin/apcupsd or /sbin/powersc).</p>
</div>
<div class="section" id="startup">
<h3><a class="toc-backref" href="#id229">Startup</a></h3>
<p>Normally, apcupsd is automatically started when
your system is rebooted. This normally occurs because the startup
script apcupsd is linked into the appropriate places in /etc/rc.d.
On most Linux systems, there is a program called chkconfig(8) that
will automatically link the startup script. This program is invoked
by the <tt class="docutils literal">make install</tt> scripts, or it is explicitly done for those
systems that do not have chkconfig(8). If this is not the case, you
can either link it in appropriately yourself or explicitly call it
from your rc.local file. The appropriate manual way to startup
apcupsd is by executing:</p>
<pre class="literal-block">
<path>/apcupsd start
</pre>
<p>where <em>path</em> is normally /etc/rc.d or /etc/rc.d/init.d depending on
your system. Using this script is
important so that any files remaining around after a power failure
are removed. Likewise, shutting down apcupsd should be done with
the same script:</p>
<pre class="literal-block">
<path>/apcupsd stop
</pre>
</div>
<div class="section" id="windows-considerations">
<h3><a class="toc-backref" href="#id230">Windows Considerations</a></h3>
<p>Please see the <a class="reference internal" href="#killpower-under-windows">Killpower under Windows</a> chapter of this manual for
considerations pertaining to shutdown and killpower on Windows.</p>
</div>
</div>
<div class="section" id="apc-smart-protocol">
<h2><a class="toc-backref" href="#id231">APC smart protocol</a></h2>
<p>The APC UPS
protocol was originally analyzed by Pavel Korensky with additions
from Andre H. Hendrick beginning in 1995, and we want to give
credit for good, hard work, where credit is due. After having said
that, you will see that Steven Freed built much of the original
apcupsd information file.</p>
<p>The start of this chapter of the apcupsd manual in HTML format was
pulled from the Network UPS Tools (NUT) site
(<a class="reference external" href="http://www.networkupstools.org/ups-protocols/apcsmart.html">http://www.networkupstools.org/ups-protocols/apcsmart.html</a>). It
has been an invaluable tool in improving apcupsd, and I consider it
the Bible of APC UPS programming. In the course of using it, I
have added information gleaned from apcupsd and information
graciously supplied by APC.</p>
<div class="section" id="description">
<h3><a class="toc-backref" href="#id232">Description</a></h3>
<p>Here's the information on the elusive APC smart signaling protocol
used by their higher end units (Back-UPS Pro, Smart-UPS,
Matrix-UPS, etc). What you see here has been collected from a
variety of sources. Some people analyzed the chatter between
PowerChute and their hardware. Others sent various characters to
the UPS and figured out what the results meant.</p>
</div>
<div class="section" id="rs-232-differences">
<h3><a class="toc-backref" href="#id233">RS-232 differences</a></h3>
<p>Normal 9 pin serial connections have TxD on 3 and RxD on 2. APC's
smart serial ports put TxD on pin 1 and RxD on pin 2. This means
you go nowhere if you use a normal straight through serial cable.
In fact, you might even power down the load if you plug one of
those cables in. This is due to the odd routing of pins - DTR and
RTS from the PC usually wind up driving the on/off line. So, when
you open the port, they go high and *poof* your computer dies.</p>
</div>
<div class="section" id="the-smart-protocol">
<h3><a class="toc-backref" href="#id234">The Smart Protocol</a></h3>
<p>Despite the lack of official information from APC, this table has
been constructed. It's standard RS-232 serial communications at
2400 bps/8N1. Don't rush the UPS while transmitting or it may stop
talking to you. This isn't a problem with the normal single
character queries, but it really does matter for multi-char things
like "@000". Sprinkle a few calls to usleep() in your code and
everything will work a lot better.</p>
<p>The following table describes the single character "Code" or
command that you can send to the UPS, its meaning, and what sort of
response the UPS will provide. Typically, the response shown below
is followed by a newline (\n in C) and a carriage return (\r in
C). If you send the UPS a command that it does not recognize or
that is not available on your UPS, it will normally respond with "NA"
for "not available", otherwise the response is given in the
"Typical results" column.</p>
<table border="1" class="docutils">
<colgroup>
<col width="12%" />
<col width="16%" />
<col width="21%" />
<col width="51%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Character</th>
<th class="head">Meaning</th>
<th class="head">Typical results</th>
<th class="head">Other info</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>^A</td>
<td>Model string</td>
<td>SMART-UPS 700</td>
<td>Spotty support for this query on older
models</td>
</tr>
<tr><td>^N</td>
<td>Turn on UPS</td>
<td>n/a</td>
<td>Send twice, with 1.5s delay between
chars. Only on 3rd gen SmartUPS and
Black Back-UPS Pros</td>
</tr>
<tr><td>^Z</td>
<td>Permitted
EEPROM
Values</td>
<td><em>long string</em></td>
<td>Gives the EEPROM permitted values for
your model. See <a class="reference internal" href="#eeprom-values">EEPROM Values</a> for
details.</td>
</tr>
<tr><td>A</td>
<td>Front panel
test</td>
<td>Light show +
"OK"</td>
<td>Also sounds the beeper for 2 seconds</td>
</tr>
<tr><td>B</td>
<td>Battery
voltage</td>
<td>27.87</td>
<td>Varies based on current level of
charge. See also Nominal Battery
Voltage.</td>
</tr>
<tr><td>C</td>
<td>Internal
Temperature</td>
<td>036.0</td>
<td>Units are degrees C</td>
</tr>
<tr><td>D</td>
<td>Runtime
calibration</td>
<td>!, then $</td>
<td>Runs until battery is below 25% (35%
for Matrix) Updates the 'j' values.
Only works at 100% battery charge. Can
be aborted with a second "D"</td>
</tr>
<tr><td>E</td>
<td>Automatic
self test
interval</td>
<td>336</td>
<td><p class="first">Writable variable. Possible values:</p>
<ul class="last simple">
<li>"336" (14 days)</li>
<li>"168" (7 days)</li>
<li>"ON " (at power on) note extra space</li>
<li>"OFF" (never)</li>
</ul>
</td>
</tr>
<tr><td>F</td>
<td>Line
frequency</td>
<td>60.00</td>
<td>Units are Hz. Value varies based on
locality, usually 50/60.</td>
</tr>
<tr><td>G</td>
<td>Cause of
last
transfer
to battery</td>
<td>O</td>
<td><p class="first">Possible values:</p>
<ul class="last simple">
<li>R (unacceptable utility voltage rate
of change)</li>
<li>H (high utility voltage)</li>
<li>L (low utility voltage)</li>
<li>T (line voltage notch or spike)</li>
<li>O (no transfers since turnon)</li>
<li>S (transfer due to U command or
activation of UPS test from front
panel)</li>
<li>NA (transfer reason still not
available; read again)</li>
</ul>
</td>
</tr>
<tr><td>I</td>
<td>Measure-UPS
Alarm enable</td>
<td>FF</td>
<td><em>not decoded yet</em></td>
</tr>
<tr><td>J</td>
<td>Measure-UPS
Alarm status</td>
<td>0F,00</td>
<td><em>not decoded yet</em></td>
</tr>
<tr><td>K</td>
<td>Shutdown
with grace
period (no
return)</td>
<td>OK or *</td>
<td>Send twice with > 1.5s delay between
chars. Older units send "*" instead of
"OK". Length of grace period is set
with Grace Period command. UPS will
remain off and NOT power on if utility
power is restored.</td>
</tr>
<tr><td>L</td>
<td>Input line
voltage</td>
<td>118.3</td>
<td>Value varies based on locality. Does
not always read 000.0 on line failure.</td>
</tr>
<tr><td>M</td>
<td>Maximum line
voltage</td>
<td>118.9</td>
<td>This is the max voltage since the last
time this query was run.</td>
</tr>
<tr><td>N</td>
<td>Minimum line
voltage</td>
<td>118.1</td>
<td>This is the min voltage since the last
time this query was run.</td>
</tr>
<tr><td>O</td>
<td>Output
voltage</td>
<td>118.3</td>
<td>Also see on battery output voltage.</td>
</tr>
<tr><td>P</td>
<td>Power load
%</td>
<td>023.5</td>
<td>Relative to capacity of the UPS.</td>
</tr>
<tr><td>Q</td>
<td>Status flags</td>
<td>08</td>
<td>Bitmapped, see <a class="reference internal" href="#status-bits">status bits</a> below</td>
</tr>
<tr><td>R</td>
<td>Turn dumb</td>
<td>BYE</td>
<td>Only on 3rd gen SmartUPS, SmartUPS
v/s, BackUPS Pro. Must send enter
smart mode command to resume comms.</td>
</tr>
<tr><td>S</td>
<td>Soft
shutdown</td>
<td>OK</td>
<td>Command executes after grace period.
UPS goes online when power returns.
Only works when on battery.</td>
</tr>
<tr><td>U</td>
<td>Simulate
power
failure</td>
<td>!, then $</td>
<td>See <a class="reference internal" href="#alert-messages">Alert messages</a> section for info
on ! and $.</td>
</tr>
<tr><td>V</td>
<td>Old firmware
revision</td>
<td>"GWD" or "IWI"</td>
<td>See <a class="reference internal" href="#interpretation-of-the-old-firmware-revision">Interpretation of the Old
Firmware Revision</a></td>
</tr>
<tr><td>W</td>
<td>Self test</td>
<td>OK</td>
<td>Tests battery, like pushing button on
the front panel. Results stored in "X"</td>
</tr>
<tr><td>X</td>
<td>Self test
results</td>
<td>OK</td>
<td><p class="first">Possible values:</p>
<ul class="last simple">
<li>OK = good battery</li>
<li>BT = failed due to insufficient
capacity</li>
<li>NG = failed due to overload</li>
<li>NO = no results available (no test
performed in last 5 minutes)</li>
</ul>
</td>
</tr>
<tr><td>Y</td>
<td>Enter smart
mode</td>
<td>SM</td>
<td>This must be sent before any other
commands will work. See also turn dumb
command to exit smart mode.</td>
</tr>
<tr><td>Z</td>
<td>Shutdown
immediately</td>
<td>n/a</td>
<td>Send twice with > 1.5s delay between
chars. UPS switches load off
immediately (no grace period)</td>
</tr>
<tr><td>a</td>
<td>Protocol
info</td>
<td><em>long string</em></td>
<td><p class="first">Returns three main sections delimited
by periods:</p>
<ul class="last simple">
<li>Protocol version</li>
<li>Alert messages (aka async notifiers)</li>
<li>Valid commands</li>
</ul>
</td>
</tr>
<tr><td>b</td>
<td>Firmware
revision</td>
<td>50.9.D</td>
<td><p class="first">See <a class="reference internal" href="#interpretation-of-the-new-firmware-revision">Interpretation of the New
Firmware Revision</a>.</p>
<p>Decoding the example:</p>
<ul class="last simple">
<li>50 = SKU (variable length)</li>
<li>9 = firmware revision</li>
<li>D = country code (D=USA,
I=International, A=Asia, J=Japan,
M=Canada)</li>
</ul>
</td>
</tr>
<tr><td>c</td>
<td>UPS local
id</td>
<td>UPS_IDEN</td>
<td>Writable variable. Up to 8 letter
identifier for keeping track of your
hardware.</td>
</tr>
<tr><td>e</td>
<td>Return
threshold</td>
<td>00</td>
<td><p class="first">Writable variable. Minimum battery
charge % before UPS will return online
after a soft shutdown. Possible
values:</p>
<ul class="last simple">
<li>00 = 00% (UPS turns on immediately)</li>
<li>01 = 15%</li>
<li>02 = 25%</li>
<li>03 = 90%</li>
</ul>
</td>
</tr>
<tr><td>f</td>
<td>Battery
level %</td>
<td>099.0</td>
<td>Percentage of battery charge remaining</td>
</tr>
<tr><td>g</td>
<td>Nominal
battery
voltage</td>
<td>024</td>
<td>The battery voltage that's expected to
be present in the UPS normally. This
is a constant based on the type,
number, and wiring of batteries in the
UPS. Typically "012", "024" or "048".</td>
</tr>
<tr><td>h</td>
<td>Measure-UPS
ambient
humidity (%)</td>
<td>042.4</td>
<td>Percentage. Only works on models with
Measure-UPS SmartSlot card.</td>
</tr>
<tr><td>i</td>
<td>Measure-UPS
dry contacts</td>
<td>00</td>
<td><p class="first">Bitmapped hex variable. Mapping:</p>
<ul class="last simple">
<li>10 = contact 1</li>
<li>20 = contact 2</li>
<li>40 = contact 3</li>
<li>80 = contact 4</li>
</ul>
</td>
</tr>
<tr><td>j</td>
<td>Estimated
runtime</td>
<td>0327:</td>
<td>Value is in minutes. Terminated with
a colon.</td>
</tr>
<tr><td>k</td>
<td>Alarm delay</td>
<td>0</td>
<td><p class="first">Writable variable. Controls behavior
of UPS beeper. Possible values:</p>
<ul class="last simple">
<li>0 = 5 second delay after power fail</li>
<li>T = 30 second delay</li>
<li>L = alarm at low battery only</li>
<li>N = no alarm</li>
</ul>
</td>
</tr>
<tr><td>l</td>
<td>Low transfer
voltage</td>
<td>103</td>
<td>Writable variable. UPS goes on battery
when voltage drops below this point.</td>
</tr>
<tr><td>m</td>
<td>Manufacture
date</td>
<td>11/29/96</td>
<td>Format may vary by country (MM/DD/YY
vs DD/MM/YY). Unique within groups of
UPSes (production runs)</td>
</tr>
<tr><td>n</td>
<td>Serial
number</td>
<td>WS9643050926</td>
<td>Unique for each UPS</td>
</tr>
<tr><td>o</td>
<td>Nominal
Output
Voltage</td>
<td>115</td>
<td>Expected output voltage when running
on batteries. May be a writable
variable on 220/230/240 VAC units.</td>
</tr>
<tr><td>p</td>
<td>Shutdown
grace delay</td>
<td>020</td>
<td>Seconds. Writable variable. Sets the
delay before soft shutdown completes.
(020/180/300/600)</td>
</tr>
<tr><td>q</td>
<td>Low battery
warning</td>
<td>02</td>
<td>Minutes. Writable variable. The UPS
will report a low battery condition
this many minutes before it runs out
of power</td>
</tr>
<tr><td>r</td>
<td>Wakeup delay</td>
<td>000</td>
<td>Seconds. Writable variable. The UPS
will wait this many seconds after
reaching the minimum charge before
returning online. (000/060/180/300)</td>
</tr>
<tr><td>s</td>
<td>Sensitivity</td>
<td>H</td>
<td><p class="first">Writable variable. Possible values:</p>
<ul class="last simple">
<li>H = highest</li>
<li>M = medium</li>
<li>L = lowest</li>
<li>A = autoadjust (Matrix only)</li>
</ul>
</td>
</tr>
<tr><td>t</td>
<td>Measure-UPS
ambient
temperature</td>
<td>80.5</td>
<td>Degrees C. Only works on models with
the Measure-UPS SmartSlot card.</td>
</tr>
<tr><td>u</td>
<td>Upper
transfer
voltage</td>
<td>132</td>
<td>Writable variable. UPS goes on battery
when voltage rises above this point.</td>
</tr>
<tr><td>v</td>
<td>Measure-UPS
firmware</td>
<td>4Kx</td>
<td>Firmware information for Measure-UPS
board</td>
</tr>
<tr><td>x</td>
<td>Last battery
change date</td>
<td>11/29/96</td>
<td>Writable variable. Holds whatever the
user set in it. Eight characters.</td>
</tr>
<tr><td>y</td>
<td>Copyright
notice</td>
<td>(C) APCC</td>
<td>Only works if firmware letter is
later than O</td>
</tr>
<tr><td>z</td>
<td>Reset to
factory
settings</td>
<td>CLEAR</td>
<td>Resets most variables to initial
factory values except identity or
battery change date. Not available on
SmartUPS v/s or BackUPS Pro.</td>
</tr>
<tr><td>+</td>
<td>Capability
cycle
(forward)</td>
<td><em>various</em></td>
<td>Cycle forward through possible
capability values. UPS sends
afterward to confirm change to EEPROM.</td>
</tr>
<tr><td>-</td>
<td>Capability
cycle
(backward)</td>
<td><em>various</em></td>
<td>Cycle backward through possible
capability values. UPS sends
afterward to confirm change to EEPROM.</td>
</tr>
<tr><td>@nnn</td>
<td>Shutdown and
return</td>
<td>OK or *</td>
<td>UPS shuts down after grace period with
delayed wakeup after nnn tenths of an
hour plus any wakeup delay time. Older
models send "*" instead of "OK".</td>
</tr>
<tr><td>0x7f</td>
<td>Abort
shutdown</td>
<td>OK</td>
<td>Use to abort @, S, K</td>
</tr>
<tr><td>~</td>
<td>Register #1</td>
<td><em>see below</em></td>
<td>See <a class="reference internal" href="#register-1">Register 1</a> table</td>
</tr>
<tr><td>'</td>
<td>Register #2</td>
<td><em>see below</em></td>
<td>See <a class="reference internal" href="#register-2">Register 2</a> table</td>
</tr>
<tr><td>0</td>
<td>Battery
constant</td>
<td> </td>
<td>See <a class="reference internal" href="#resetting-the-ups-battery-constant">Resetting the UPS Battery
Constant</a></td>
</tr>
<tr><td>4</td>
<td><em>???</em></td>
<td> </td>
<td>Prints 35 on SmartUPS 1000</td>
</tr>
<tr><td>5</td>
<td><em>???</em></td>
<td> </td>
<td>Prints EF on SmartUPS 1000</td>
</tr>
<tr><td>6</td>
<td><em>???</em></td>
<td> </td>
<td>Prints F9 on SmartUPS 1000</td>
</tr>
<tr><td>7</td>
<td>DIP switch
positions</td>
<td> </td>
<td>See <a class="reference internal" href="#dip-switch-info">Dip switch info</a></td>
</tr>
<tr><td>8</td>
<td>Register #3</td>
<td><em>see below</em></td>
<td>See <a class="reference internal" href="#register-3">Register 3</a> table</td>
</tr>
<tr><td>9</td>
<td>Line quality</td>
<td>FF</td>
<td><p class="first">Possible values:</p>
<ul class="last simple">
<li>00 = unacceptable</li>
<li>FF = acceptable</li>
</ul>
</td>
</tr>
<tr><td>></td>
<td>Number of
external
battery
packs</td>
<td> </td>
<td>SmartCell models return number of
connected packs. Other models return
value set by the user (use +/-).</td>
</tr>
<tr><td>[</td>
<td>Measure-UPS
Upper temp
limit</td>
<td>NO,NO</td>
<td>Degrees C. Writable Variable. Possible
values: 55, 50, 45, ..., 05.
Use +/- to change values.</td>
</tr>
<tr><td>]</td>
<td>Measure-UPS
lower temp
limit</td>
<td>NO,NO</td>
<td>Degrees C. Writable Variable. Possible
values: 55, 50, 45, ..., 05.
Use +/- to change values.</td>
</tr>
<tr><td>{</td>
<td>Measure-UPS
Upper
humidity
limit</td>
<td>NO,NO</td>
<td>Percentage. Writable Variable.
Possible values: 90, 80, 70, ..., 10.
Use +/- to change values.</td>
</tr>
<tr><td>}</td>
<td>Measure-UPS
lower
humidity
limit</td>
<td>NO,NO</td>
<td>Percentage. Writable Variable.
Possible values: 90, 80, 70, ..., 10.
Use +/- to change values.</td>
</tr>
<tr><td colspan="4"><strong>Matrix-UPS and Symmetra Commands</strong></td>
</tr>
<tr><td>^</td>
<td>Run in
bypass mode</td>
<td>BYP, INV, ERR</td>
<td>If online, "BYP" response is received
as bypass mode starts. If already in
bypass, "INV" is received and UPS goes
online. If UPS can't transfer, "ERR"
received</td>
</tr>
<tr><td><</td>
<td>Number of
bad battery
packs</td>
<td>000</td>
<td>Count of bad packs connected to the
UPS</td>
</tr>
<tr><td>/</td>
<td>Load current</td>
<td><em>nn.nn</em></td>
<td>True RMS load current drawn by UPS</td>
</tr>
<tr><td>\</td>
<td>Apparent
load power</td>
<td><em>nnn.nn</em></td>
<td>Output load as percentage of full
rated load in VA.</td>
</tr>
<tr><td>^V</td>
<td>Output
voltage
selection</td>
<td> </td>
<td><p class="first">Writable variable. Possible values:</p>
<ul class="last simple">
<li>A = automatic (based on input tap)</li>
<li>M = 208 VAC</li>
<li>I = 240 VAC</li>
</ul>
</td>
</tr>
<tr><td>^L</td>
<td>Front panel
language</td>
<td> </td>
<td><p class="first">Writable variable. Possible values:</p>
<ul class="last simple">
<li>E = English</li>
<li>F = French</li>
<li>G = German</li>
<li>S = Spanish</li>
<li>1 = <em>unknown</em></li>
<li>2 = <em>unknown</em></li>
<li>3 = <em>unknown</em></li>
<li>4 = <em>unknown</em></li>
</ul>
</td>
</tr>
<tr><td>w</td>
<td>Run time
conservation</td>
<td> </td>
<td><p class="first">Writable variable. Minutes of runtime
to leave in battery (UPS shuts down
"early"). Possible values:</p>
<ul class="last simple">
<li>NO = disabled</li>
<li>02 = leave 2 minutes of runtime</li>
<li>05 = leave 5 minutes</li>
<li>08 = leave 8 minutes</li>
</ul>
</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="dip-switch-info">
<h3><a class="toc-backref" href="#id235">Dip switch info</a></h3>
<table border="1" class="docutils">
<colgroup>
<col width="4%" />
<col width="8%" />
<col width="88%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Bit</th>
<th class="head">Switch</th>
<th class="head">Option when bit=1</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>0</td>
<td>4</td>
<td>Low battery alarm changed from 2 to 5 mins. Autostartup disabled on
SU370ci and 400</td>
</tr>
<tr><td>1</td>
<td>3</td>
<td>Audible alarm delayed 30 seconds</td>
</tr>
<tr><td>2</td>
<td>2</td>
<td>Output transfer set to 115 VAC (from 120 VAC) or to 240 VAC (from
230 VAC)</td>
</tr>
<tr><td>3</td>
<td>1</td>
<td>UPS desensitized - input voltage range expanded</td>
</tr>
<tr><td>4-7</td>
<td> </td>
<td>Unused at this time</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="status-bits">
<h3><a class="toc-backref" href="#id236">Status bits</a></h3>
<p>This is probably the most important register of the UPS, which
indicates the overall UPS status. Some common things you'll see:</p>
<ul class="simple">
<li>08 = On line, battery OK</li>
<li>10 = On battery, battery OK</li>
<li>50 = On battery, battery low</li>
<li>SM = Status bit is still not available (retry reading)</li>
</ul>
<table border="1" class="docutils">
<colgroup>
<col width="4%" />
<col width="96%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Bit</th>
<th class="head">Meaning when bit=1</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>0</td>
<td>Runtime calibration occurring
(Not reported by Smart UPS v/s and BackUPS Pro)</td>
</tr>
<tr><td>1</td>
<td>SmartTrim (Not reported by 1st and 2nd generation SmartUPS models)</td>
</tr>
<tr><td>2</td>
<td>SmartBoost</td>
</tr>
<tr><td>3</td>
<td>On line (this is the normal condition)</td>
</tr>
<tr><td>4</td>
<td>On battery</td>
</tr>
<tr><td>5</td>
<td>Overloaded output</td>
</tr>
<tr><td>6</td>
<td>Battery low</td>
</tr>
<tr><td>7</td>
<td>Replace battery</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="alert-messages">
<h3><a class="toc-backref" href="#id237">Alert messages</a></h3>
<p>These single character messages are sent by the UPS any time there
is an Alert condition. All other responses indicated above are sent
by the UPS only in response to a query or action command.</p>
<table border="1" class="docutils">
<colgroup>
<col width="12%" />
<col width="17%" />
<col width="72%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Character</th>
<th class="head">Meaning</th>
<th class="head">Description</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>!</td>
<td>Line Fail</td>
<td>Sent when the UPS goes on-battery, repeated every 30
seconds until low battery condition reached. Sometimes
occurs more than once in the first 30 seconds.</td>
</tr>
<tr><td>$</td>
<td>Return from
line fail</td>
<td>UPS back on line power. Only sent if a ! has been sent
previously.</td>
</tr>
<tr><td>%</td>
<td>Low battery</td>
<td>Sent to indicate low battery. Not implemented on
SmartUPS v/s or BackUPS Pro models</td>
</tr>
<tr><td>+</td>
<td>Return from
low batt</td>
<td>Sent when the battery has been recharged to some level
Only sent if a % has been sent previously.</td>
</tr>
<tr><td>?</td>
<td>Abnormal
condition</td>
<td>Sent for conditions such as "shutdown due to overload"
or "shutdown due to low battery capacity". Also occurs
within 10 minutes of turnon.</td>
</tr>
<tr><td>=</td>
<td>Return from
abnormal
condition</td>
<td>Sent when the UPS returns from an abnormal condition
where ? was sent, but not a turn-on. Not implemented on
SmartUPS v/s or BackUPS Pro models.</td>
</tr>
<tr><td>*</td>
<td>About to
turn off</td>
<td>Sent when the UPS is about to switch off the load. No
commands are processed after this character is sent. Not
implemented on SmartUPS v/s, BackUPS Pro, or 3rd
generation SmartUPS models.</td>
</tr>
<tr><td>#</td>
<td>Replace
battery</td>
<td>Sent when the UPS detects that the battery needs to be
replaced. Sent every 5 hours until a new battery test is
run or the UPS is shut off. Not implemented on SmartUPS
v/s or BackUPS Pro models.</td>
</tr>
<tr><td>&</td>
<td>Check alarm
register
for fault
(Measure-UPS)</td>
<td>Sent to signal that temp or humidity out of set limits.
Also sent when one of the contact closures changes
state. Sent every 2 minutes until the alarm conditions
are reset. Only sent for alarms enabled with I. Cause of
alarm may be determined with J. Not implemented on
SmartUPS v/s or BackUPS Pro.</td>
</tr>
<tr><td>|</td>
<td>Variable
change in
EEPROM</td>
<td>Sent whenever any EEPROM variable is changed. Only
supported on Matrix UPS and 3rd generation SmartUPS
models.</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="register-1">
<h3><a class="toc-backref" href="#id238">Register 1</a></h3>
<p>All bits are valid on the Matrix UPS. SmartUPS models only support
bits 6 and 7. Other models do not respond.</p>
<table border="1" class="docutils">
<colgroup>
<col width="4%" />
<col width="96%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Bit</th>
<th class="head">Meaning when bit=1</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>0</td>
<td>In wakeup mode (typically lasts < 2s)</td>
</tr>
<tr><td>1</td>
<td>In bypass mode due to internal fault (see <a class="reference internal" href="#register-2">Register 2</a> or <a class="reference internal" href="#register-3">Register 3</a>)</td>
</tr>
<tr><td>2</td>
<td>Going to bypass mode due to command</td>
</tr>
<tr><td>3</td>
<td>In bypass mode due to command</td>
</tr>
<tr><td>4</td>
<td>Returning from bypass mode</td>
</tr>
<tr><td>5</td>
<td>In bypass mode due to manual bypass control</td>
</tr>
<tr><td>6</td>
<td>Ready to power load on user command</td>
</tr>
<tr><td>7</td>
<td>Ready to power load on user command or return of line power</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="register-2">
<h3><a class="toc-backref" href="#id239">Register 2</a></h3>
<p>Matrix UPS models report bits 0-5. SmartUPS models only support
bits 4-6. SmartUPS v/s and BackUPS Pro report bits 4, 6, 7.
Unused bits are set to 0. Other models do not respond.</p>
<table border="1" class="docutils">
<colgroup>
<col width="4%" />
<col width="96%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Bit</th>
<th class="head">Meaning when bit=1</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>0</td>
<td>Fan failure in electronics, UPS in bypass</td>
</tr>
<tr><td>1</td>
<td>Fan failure in isolation unit</td>
</tr>
<tr><td>2</td>
<td>Bypass supply failure</td>
</tr>
<tr><td>3</td>
<td>Output voltage select failure, UPS in bypass</td>
</tr>
<tr><td>4</td>
<td>DC imbalance, UPS in bypass</td>
</tr>
<tr><td>5</td>
<td>Battery is disconnected</td>
</tr>
<tr><td>6</td>
<td>Relay fault in SmartTrim or SmartBoost</td>
</tr>
<tr><td>7</td>
<td>Bad output voltage</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="register-3">
<h3><a class="toc-backref" href="#id240">Register 3</a></h3>
<p>All bits are valid on the Matrix UPS and 3rd generation SmartUPS
models. SmartUPS v/s and BackUPS Pro models report bits 0-5. All
others report 0-4. State change of bits 1,2,5,6,7 are reported
asynchronously with ? and = messages.</p>
<table border="1" class="docutils">
<colgroup>
<col width="4%" />
<col width="96%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Bit</th>
<th class="head">Meaning when bit=1</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>0</td>
<td>Output unpowered due to shutdown by low battery</td>
</tr>
<tr><td>1</td>
<td>Unable to transfer to battery due to overload</td>
</tr>
<tr><td>2</td>
<td>Main relay malfunction - UPS turned off</td>
</tr>
<tr><td>3</td>
<td>In sleep mode from @ command (maybe others)</td>
</tr>
<tr><td>4</td>
<td>In shutdown mode from S command</td>
</tr>
<tr><td>5</td>
<td>Battery charger failure</td>
</tr>
<tr><td>6</td>
<td>Bypass relay malfunction</td>
</tr>
<tr><td>7</td>
<td>Normal operating temperature exceeded</td>
</tr>
</tbody>
</table>
</div>
<div class="section" id="interpretation-of-the-old-firmware-revision">
<h3><a class="toc-backref" href="#id241">Interpretation of the Old Firmware Revision</a></h3>
<p>The Old Firmware Revision is obtained with the "V" command, which
gives a typical response such as "GWD" or "IWI", and can be
interpreted as follows:</p>
<pre class="literal-block">
Old Firmware revision and model ID String for SmartUPS & MatrixUPS
This is a three character string XYZ
where X == Smart-UPS or Matrix-UPS ID Code.
range 0-9 and A-P
1 == unknown
0 == Matrix 3000
5 == Matrix 5000
the rest are Smart-UPS and Smart-UPS-XL
2 == 250 3 == 400 4 == 400
6 == 600 7 == 900 8 == 1250
9 == 2000 A == 1400 B == 1000
C == 650 D == 420 E == 280
F == 450 G == 700 H == 700XL
I == 1000 J == 1000XL K == 1400
L == 1400XL M == 2200 N == 2200XL
O == 3000 P == 5000
where Y == Possible Level of Smart Features, unknown???
G == Stand Alone
T == Stand Alone
V == ???
W == Rack Mount
where Z == National Model Use Only Codes
D == Domestic 115 Volts
I == International 230 Volts
A == Asia ?? 100 Volts
J == Japan ?? 100 Volts
</pre>
</div>
<div class="section" id="interpretation-of-the-new-firmware-revision">
<h3><a class="toc-backref" href="#id242">Interpretation of the New Firmware Revision</a></h3>
<pre class="literal-block">
New Firmware revision and model ID String in NN.M.L is the format
where NN == UPS ID Code.
12 == Back-UPS Pro 650
13 == Back-UPS Pro 1000
52 == Smart-UPS 700
60 == SmartUPS 1000
72 == Smart-UPS 1400
where NN now Nn has possible meanings.
N == Class of UPS
1n == Back-UPS Pro
5n == Smart-UPS
7n == Smart-UPS NET
n == Level of intelligence
N1 == Simple Signal, if detectable WAG(*)
N2 == Full Set of Smart Signals
N3 == Micro Subset of Smart Signals
where M == Possible Level of Smart Features, unknown???
1 == Stand Alone
8 == Rack Mount
9 == Rack Mount
where L == National Model Use Only Codes
D == Domestic 115 Volts
I == International 230 Volts
A == Asia ?? 100 Volts
J == Japan ?? 100 Volts
M == North America 208 Volts (Servers)
</pre>
</div>
<div class="section" id="eeprom-values">
<h3><a class="toc-backref" href="#id243">EEPROM Values</a></h3>
<p>Upon sending a ^Z, your UPS will probably spit back approximately
254 characters something like the following (truncated here for the
example):</p>
<pre class="literal-block">
#uD43132135138129uM43229234239224uA43110112114108 ....
</pre>
<p>It looks bizarre and ugly, but is easily parsed. The # is some kind
of marker/ident character. Skip it. The rest fits this form:</p>
<ul class="simple">
<li>Command character - use this to select the value</li>
<li>Locale - use 'b' to find out what yours is (the last character),
'4' applies to all</li>
<li>Number of choices - '4' means there are 4 possibilities coming
up</li>
<li>Choice length - '3' means they are all 3 chars long</li>
</ul>
<p>Then it's followed by the choices, and it starts over.</p>
<p>Matrix-UPS models have ## between each grouping for some reason.</p>
<p>Here is an example broken out to be more readable:</p>
<pre class="literal-block">
CMD DFO RSP FSZ FVL
u D 4 3 127 130 133 136
u M 4 3 229 234 239 224
u A 4 3 108 110 112 114
u I 4 3 253 257 261 265
l D 4 3 106 103 100 097
l M 4 3 177 172 168 182
l A 4 3 092 090 088 086
l I 4 3 208 204 200 196
e 4 4 2 00 15 50 90
o D 1 3 115
o J 1 3 100
o I 1 3 230 240 220 225
o M 1 3 208
s 4 4 1 H M L L
q 4 4 2 02 05 07 10
p 4 4 3 020 180 300 600
k 4 4 1 0 T L N
r 4 4 3 000 060 180 300
E 4 4 3 336 168 ON OFF
CMD == UPSlink Command.
u = upper transfer voltage
l = lower transfer voltage
e = return threshold
o = output voltage
s = sensitivity
p = shutdown grace delay
q = low battery warning
k = alarm delay
r = wakeup delay
E = self test interval
DFO == (4)-all-countries (D)omestic (I)nternational (A)sia (J)apan
(M) North America - servers.
RSP == Total number possible answers returned by a given CMD.
FSZ == Max. number of field positions to be filled.
FVL == Values that are returned and legal.
</pre>
</div>
<div class="section" id="programming-the-ups-eeprom">
<h3><a class="toc-backref" href="#id244">Programming the UPS EEPROM</a></h3>
<p>There are at this time a maximum of 12 different values that can be
programmed into the UPS EEPROM. They are:</p>
<table border="1" class="docutils">
<colgroup>
<col width="9%" />
<col width="91%" />
</colgroup>
<thead valign="bottom">
<tr><th class="head">Command</th>
<th class="head">Meaning</th>
</tr>
</thead>
<tbody valign="top">
<tr><td>c</td>
<td>The UPS Id or name</td>
</tr>
<tr><td>x</td>
<td>The last date the batteries were replaced</td>
</tr>
<tr><td>u</td>
<td>The Upper Transfer Voltage</td>
</tr>
<tr><td>l</td>
<td>The Lower Transfer Voltage</td>
</tr>
<tr><td>e</td>
<td>The Return Battery Charge Percentage</td>
</tr>
<tr><td>o</td>
<td>The Output Voltage when on Batteries</td>
</tr>
<tr><td>s</td>
<td>The Sensitivity to Line Quality</td>
</tr>
<tr><td>p</td>
<td>The Shutdown Grace Delay</td>
</tr>
<tr><td>q</td>
<td>The Low Battery Warning Delay</td>
</tr>
<tr><td>k</td>
<td>The Alarm Delay</td>
</tr>
<tr><td>r</td>
<td>The Wakeup Delay</td>
</tr>
<tr><td>E</td>
<td>The Automatic Self Test Interval</td>
</tr>
</tbody>
</table>
<p>The first two cases (Ident and Batt date) are somewhat special in
that you tell the UPS you want to change the value, then you supply
8 characters that are saved in the EEPROM. The last ten item are
programmed by telling the UPS that you want it to cycle to the next
permitted value.</p>
<p>In each case, you indicate to the UPS that you want to change the
EEPROM by first sending the appropriate query command (e.g. "c" for
the UPS ID or "u" for the Upper Transfer voltage. This command is
then immediately followed by the cycle EEPROM command or "-". In
the case of the UPS Id or the battery date, you follow the cycle
command by the eight characters that you want to put in the EEPROM.
In the case of the other ten items, there is nothing more to
enter.</p>
<p>The UPS will respond by "OK" and approximately 5 seconds later by a
vertical bar (|) to indicate that the EEPROM was changed.</p>
</div>
</div>
<div class="section" id="nis-network-server-protocol">
<h2><a class="toc-backref" href="#id245">NIS Network Server Protocol</a></h2>
<p>The NIS network server in apcupsd is capable of sending status and events data
to clients that request it. The communication between the client and the server
is performed over a TCP connection to the NISPORT (normally port 3551). The
client opens a connection to the server and sends a message, to which the
server will reply with one or more messages. Each message consists of a 2-byte
length (in network byte order) followed by that many bytes of data. Both the
client->server and server->client messages follow this format.</p>
<p>apcupsd supports two commands, sent as the body of a message:</p>
<ol class="arabic simple">
<li>"status" - The status command requests that the server send a copy of all
status values, in the form displayed by apcaccess. After the client sends the
"status" command, the server will reply with a series of messges, each one
containing one line of apcaccess status data. The end of the command series
is indicated by an empty message (length of 0).</li>
<li>"events" - The events command operates the same as "status" except the
server replies with lines from the log of recent events.</li>
</ol>
<p>As an example, the following bytes would be sent by a client to solicit the status:</p>
<pre class="literal-block">
0x00 0x06 0x73 0x74 0x61 0x74 0x75 0x73
</pre>
<p>The first two bytes are the data length (6) in network byte order. The 6 bytes
of data that follow are the ASCII characters for "status". The server will
respond to this command with a series of its own messages containing the status
data.</p>
</div>
<div class="section" id="apcupsd-rpm-packaging-faq">
<h2><a class="toc-backref" href="#id246">Apcupsd RPM Packaging FAQ</a></h2>
<dl class="docutils">
<dt><strong>How do I build Apcupsd for platform xxx?</strong></dt>
<dd><p class="first">The apcupsd spec file contains defines
to build for several platforms: RedHat 7.x (rh7), RedHat 8.0 (rh8),
RedHat 9 (rh9), Fedora Core (fedora_core), RedHat Enterprise Linux
and clones (rhel3 and rhel4), SuSE 9 & 10 (suse), and Mandrake
(mdk). The package build is controlled by a define set at the
beginning of the file. These defines basically just control the
dependency information that gets coded into the finished rpm
package. So while you could technically build a package without
defining a platform, or with an incorrect platform, and have it
install and run it would not contain correct dependency information
for the rpm database. The platform define may be edited in the spec
file directly (by default all defines are set to 0 or "not set").
For example, to build the RedHat 7.x package find the line in the
spec file which reads</p>
<pre class="literal-block">
%define rh7 0
</pre>
<p>and edit it to read</p>
<pre class="literal-block">
%define rh7 1
</pre>
<p>Alternately you may pass the define on the command line when
calling rpmbuild:</p>
<pre class="last literal-block">
rpmbuild -ba --define "build_rh7 1" apcupsd.spec
rpmbuild --rebuild --define build_rh7 1" apcupsd-x.x.x-x.src.rpm
</pre>
</dd>
<dt><strong>How do I control whether usb support gets built?</strong></dt>
<dd><p class="first">Up through version 3.12, by default standard serial port support was built
and the apcupsd-std package was produced. The usb package pre-configured
the configuration files for usb devices and installed a couple
additional tools in /etc/apcupsd but the usb driver was built
regardless. To get the usb package and support in those versions
either set the</p>
<pre class="literal-block">
%define usb 0
</pre>
<p>to</p>
<pre class="literal-block">
%define usb 1
</pre>
<p>in the spec file directly or pass it to rpmbuild on the command
line:</p>
<pre class="literal-block">
rpmbuild -ba --define "build_rh7 1" --define "build_usb 1" apcupsd.spec
</pre>
<p>With the release of 3.14 USB support is now considered standard and
the apcupsd-std and apcupsd-usb packages are obsoleted in favor of
a single apcupsd package configured for usb connected UPS's. The
serial port driver is still built and can be configured accordingly
after installation. If you are performing an upgrade it will of
course not replace your current config file.</p>
<p>The build directive:</p>
<pre class="literal-block">
--define "build_usb 1"
</pre>
<p class="last">is no longer recognized.</p>
</dd>
<dt><strong>What other defines are used?</strong></dt>
<dd><p class="first">There is a define for the initdir for the daemon control script. On
RedHat or Mandrake systems this is set to /etc/rc.d/init.d/. On
SuSE systems this is set to /etc/rc.d. You would only need to edit
this if packaging for a platform that uses a different directory.</p>
<p>A second define controls whether the Gnome monitoring application,
new in the 3.14 release, is built. This application requires the
Gtk2 version to be >= 2.4. If you want to build the apcupsd-gapcmon
package add:</p>
<pre class="literal-block">
--define "build_gapcmon 1"
</pre>
<p>A third define controls whether the SNMP driver is built. If you
want to build the net-snmp driver add:</p>
<pre class="last literal-block">
--define "build_snmp 1"
</pre>
</dd>
<dt><strong>Can I supply packages for other platforms you do not publish?</strong></dt>
<dd>Yes, there are tools provided for contributors to supply rpm
packages for platforms for which support is provided in the spec
file but for which the development team chooses not to release
binary packages, usually due to lack of interest or lack of an
available platform. Please see platforms/contrib/README in the
source package.</dd>
<dt><strong>I'm getting errors about not having permission when I try to build the packages. Do I need to be root?</strong></dt>
<dd><p class="first">No, you do not need to be root
and, in fact, it is better practice to build rpm packages as a
non-root user. Apcupsd's packages are designed to be built by a
regular user but you must make a few changes on your system to do
this. If you are building on your own system then the simplest
method is to add write permissions for all to the build directory
(/usr/src/redhat/). To accomplish this execute one of the following
commands as root depending on your distribution, RedHat, SuSE or
Mandriva, respectively:</p>
<pre class="literal-block">
chmod -R 777 /usr/src/redhat
chmod -R 777 /usr/src/packages
chmod -R 777 /usr/src/RPM
</pre>
<p>If you are working on a shared system where you can not use the
method above then you need to recreate the /usr/src/redhat (or
other) directory tree with all of it's subdirectories inside your
home directory. Then create a file named</p>
<pre class="literal-block">
.rpmmacros
</pre>
<p>in your home directory (or edit the file if it already exists) and
add the following line:</p>
<pre class="last literal-block">
%_topdir /home/myuser/redhat
</pre>
</dd>
</dl>
</div>
<div class="section" id="credits">
<h2><a class="toc-backref" href="#id247">Credits</a></h2>
<img alt="./thanks.png" src="./thanks.png" />
<p>The success of apcupsd is due to the many people that helped in
development, testing and in many other ways.</p>
<p>Thank all the developers that worked hard to make APCUPSD one of the
best piece of software for UPS management.</p>
<div class="section" id="contributors">
<h3><a class="toc-backref" href="#id248">Contributors</a></h3>
<dl class="docutils">
<dt><strong>Current Code Maintainer and Project Manager</strong></dt>
<dd>Adam Kropelin (<a class="reference external" href="mailto:adam@kroptech.com">adam@kroptech.com</a>)</dd>
<dt><strong>RPM Packager</strong></dt>
<dd>D. Scott Barninger</dd>
<dt><strong>CGI and HTML fixer</strong></dt>
<dd>William King (<a class="reference external" href="mailto:wrking@dadaboom.com">wrking@dadaboom.com</a>)</dd>
<dt><strong>Former Project Manager</strong></dt>
<dd>Kern Sibbald (<a class="reference external" href="mailto:kern@sibbald.com">kern@sibbald.com</a>)</dd>
<dt><strong>Project Starter and Former Code Maintainer</strong></dt>
<dd>Andre Hedrick (<a class="reference external" href="mailto:andre@linux-ide.org">andre@linux-ide.org</a>)</dd>
<dt><strong>Former Code Maintainer and Project Manager</strong></dt>
<dd>Riccardo Facchetti (<a class="reference external" href="mailto:riccardo@master.oasi.gpa.it">riccardo@master.oasi.gpa.it</a>)</dd>
<dt><strong>Serial Communications</strong></dt>
<dd>Andre Hedrick (<a class="reference external" href="mailto:andre@linux-ide.org">andre@linux-ide.org</a>)</dd>
<dt><strong>2.0 User's Manual</strong></dt>
<dd>Eric S. Raymond (<a class="reference external" href="mailto:esr@thyrsus.com">esr@thyrsus.com</a>)</dd>
<dt><strong>Alpha Port</strong></dt>
<dd>Kern Sibbald (<a class="reference external" href="mailto:kern@sibbald.com">kern@sibbald.com</a>)
J. Rochate (<a class="reference external" href="mailto:jrochate@ualg.pt">jrochate@ualg.pt</a>) testing and machine loan</dd>
<dt><strong>Caldera</strong></dt>
<dd>John Pinner (<a class="reference external" href="mailto:john@clocksoft.com">john@clocksoft.com</a>)</dd>
<dt><strong>HP-UX Port</strong></dt>
<dd>Carl Erhorn (<a class="reference external" href="mailto:Carl_Erhorn@hyperion.com">Carl_Erhorn@hyperion.com</a>)
Robert K Nelson (<a class="reference external" href="mailto:rnelson@airflowsciences.com">rnelson@airflowsciences.com</a>)</dd>
<dt><strong>SOLARIS Port</strong></dt>
<dd>Carl Erhorn (<a class="reference external" href="mailto:Carl_Erhorn@hyperion.com">Carl_Erhorn@hyperion.com</a>)</dd>
<dt><strong>OpenBSD Port</strong></dt>
<dd>Devin Reade (<a class="reference external" href="mailto:gdr@gno.org">gdr@gno.org</a>)</dd>
<dt><strong>NetBSD Port</strong></dt>
<dd>Neil Darlow (<a class="reference external" href="mailto:neil@darlow.co.uk">neil@darlow.co.uk</a>)</dd>
<dt><strong>Win32 Port</strong></dt>
<dd>Kern Sibbald (<a class="reference external" href="mailto:kern@sibbald.com">kern@sibbald.com</a>)
Paul Z. Stagner</dd>
<dt><strong>WEB Interfaces</strong></dt>
<dd>Kern Sibbald (<a class="reference external" href="mailto:kern@sibbald.com">kern@sibbald.com</a>)
Joseph Acosta (<a class="reference external" href="mailto:joeja@mindspring.com">joeja@mindspring.com</a>)</dd>
</dl>
</div>
<div class="section" id="apcupsd-license">
<h3><a class="toc-backref" href="#id249">Apcupsd License</a></h3>
<p>Apcupsd is licensed under the terms of the GNU General Public License, version 2
(GPLv2). The full text of this license may be found in the COPYING file at the
top of the source tree and online at <a class="reference external" href="http://www.gnu.org/licenses/gpl-2.0.html">http://www.gnu.org/licenses/gpl-2.0.html</a>.</p>
<p>Source files are copyright of their specific author(s), as noted in the files.</p>
<pre class="literal-block">
This program is free software; you can redistribute it and/or
modify it under the terms of version 2 of the GNU General
Public License as published by the Free Software Foundation.
This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
General Public License for more details.
You should have received a copy of the GNU General Public
License along with this program; if not, write to the Free
Software Foundation, 51 Franklin Street, Fifth Floor, Boston,
MA 02110-1335, USA.
</pre>
</div>
<div class="section" id="other-open-source-licenses">
<h3><a class="toc-backref" href="#id250">Other Open Source Licenses</a></h3>
<p>Apcupsd incorporates the libusbhid library which is subject to the following
copyright and license:</p>
<pre class="literal-block">
Copyright (c) 1999 Lennart Augustsson <augustss@netbsd.org>
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions
are met:
1. Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
SUCH DAMAGE.
</pre>
</div>
</div>
</div>
</div>
<div class="footer">
<hr class="footer" />
Generated on: 2015-02-08 17:53 UTC.
Generated by <a class="reference external" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference external" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
</div>
</body>
</html>
|