~iheino+ub/+junk/nut-upsconf-docfix

This man page only documents the hardware\-specific features of the usbhid\-ups driver\&. For information about the core driver, see \fBnutupsdrv\fR(8)\&.

.sp

This driver, formerly called \fInewhidups\fR, replaces the legacy \fIhidups\fR driver, which only supported Linux systems\&.

.SH "SUPPORTED HARDWARE"

.sp

\fBusbhid\-ups\fR brings USB/HID UPS monitoring to NUT on all platform supporting USB through libusb\&. It should detect any UPS that uses the HID power device class, but the amount of data will vary depending on the manufacturer and model\&.

.sp

At the present time, usbhid\-ups supports:

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

the newer Eaton USB models,

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

all MGE USB models,

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

all Dell USB models,

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

some APC models,

.RE

.sp

.RS 4

.ie n \{\

\h'-04'\(bu\h'+03'\c

.\}

.el \{\

.sp -1

.IP \(bu 2.3

.\}

some Belkin models,

.RE

.sp

.RS 4

.ie n \{\

100

\h'-04'\(bu\h'+03'\c

101

.\}

102

.el \{\

103

.sp -1

104

.IP \(bu 2.3

105

.\}

106

some Cyber Power Systems models\&.

107

.RE

108

.sp

109

.RS 4

110

.ie n \{\

111

\h'-04'\(bu\h'+03'\c

112

.\}

113

.el \{\

114

.sp -1

115

.IP \(bu 2.3

116

.\}

117

some TrippLite models

118

.RE

119

.sp

120

For a more complete list, refer to the NUT hardware compatibility list, available in the source distribution as data/drivers\&.list, or on the NUT website\&. You may use the "explore" driver option to gather information from HID UPSes which are not yet supported; see below for details\&.

121

.sp

122

This driver is known to work on:

123

.sp

124

.RS 4

125

.ie n \{\

126

\h'-04'\(bu\h'+03'\c

127

.\}

128

.el \{\

129

.sp -1

130

.IP \(bu 2.3

131

.\}

132

most Linux systems,

133

.RE

134

.sp

135

.RS 4

136

.ie n \{\

137

\h'-04'\(bu\h'+03'\c

138

.\}

139

.el \{\

140

.sp -1

141

.IP \(bu 2.3

142

.\}

143

FreeBSD (beta stage) and maybe other *BSD,

144

.RE

145

.sp

146

.RS 4

147

.ie n \{\

148

\h'-04'\(bu\h'+03'\c

149

.\}

150

.el \{\

151

.sp -1

152

.IP \(bu 2.3

153

.\}

154

Darwin / Mac OS X,

155

.RE

156

.sp

157

.RS 4

158

.ie n \{\

159

\h'-04'\(bu\h'+03'\c

160

.\}

161

.el \{\

162

.sp -1

163

.IP \(bu 2.3

164

.\}

165

Solaris 10\&.

166

.RE

167

.SH "EXTRA ARGUMENTS"

168

.sp

169

This driver also supports the following optional settings:

170

.PP

171

\fBoffdelay\fR=\fInum\fR

172

.RS 4

173

Set the timer before the UPS is turned off after the kill power command is sent (via the

174

\fB\-k\fR

175

switch)\&.

176

.sp

177

The default value is 20 (in seconds)\&. Usually this

178

\fBmust be lower\fR

179

than

180

\fIondelay\fR, but the driver will

181

\fBnot\fR

182

warn you upon startup if it isn\(cqt\&.

183

.RE

184

.PP

185

\fBondelay\fR=\fInum\fR

186

.RS 4

187

Set the timer for the UPS to switch on in case the power returns after the kill power command had been sent but before the actual switch off\&. This ensures the machines connected to the UPS are, in all cases, rebooted after a power failure\&.

188

.sp

189

The default value is 30 (in seconds)\&. Usually this

190

\fBmust be greater\fR

191

than offdelay, but the driver will

192

\fBnot\fR

193

warn you upon startup if it isn\(cqt\&. Some UPS\(cqes will restart no matter what, even if the power is (still) out at the moment this timer elapses\&. In that case, you could try if setting

194

\fIondelay = \-1\fR

195

196

\fBups\&.conf\fR

197

helps\&.

198

.RE

199

.PP

200

\fBpollfreq\fR=\fInum\fR

201

.RS 4

202

Set polling frequency, in seconds, to reduce the USB data flow\&. Between two polling requests, the driver will wait for interrupts (aka UPS notifications), which are data changes returned by the UPS by itself\&. This mechanism allow to avoid or reduce staleness message, due to the UPS being temporarily overloaded with too much polling requests\&. The default value is 30 (in seconds)\&.

203

.RE

204

.PP

205

\fBpollonly\fR

206

.RS 4

207

If this flag is set, the driver will ignore interrupts it receives from the UPS (not recommended, but needed if these reports are broken on your UPS)\&.

208

.RE

209

.PP

210

\fBvendor\fR=\fIregex\fR, \fBproduct\fR=\fIregex\fR, \fBserial\fR=\fIregex\fR, \fBvendorid\fR=\fIregex\fR, \fBproductid\fR=\fIregex\fR

211

.RS 4

212

Select a specific UPS, in case there is more than one connected via USB Each option specifies an extended regular expression (see regex(7)) that must match the UPS\(cqs entire vendor/product/serial string (minus any surrounding whitespace), or the whole 4\-digit hexadecimal code for vendorid and productid\&. Try

213

\fB\-DD\fR

214

for finding out the strings to match\&.

215

.sp

216

Examples:

217

.sp

218

.RS 4

219

.ie n \{\

220

\h'-04'\(bu\h'+03'\c

221

.\}

222

.el \{\

223

.sp -1

224

.IP \(bu 2.3

225

.\}

226

227

\-x vendor="Foo\&.Corporation\&.*"

228

.RE

229

.sp

230

.RS 4

231

.ie n \{\

232

\h'-04'\(bu\h'+03'\c

233

.\}

234

.el \{\

235

.sp -1

236

.IP \(bu 2.3

237

.\}

238

239

\-x vendorid=051d*

240

(APC)

241

.RE

242

.sp

243

.RS 4

244

.ie n \{\

245

\h'-04'\(bu\h'+03'\c

246

.\}

247

.el \{\

248

.sp -1

249

.IP \(bu 2.3

250

.\}

251

252

\-x product="\&.*(Smart|Back)\-?UPS\&.*"

253

.RE

254

.RE

255

.PP

256

\fBbus\fR=\fIregex\fR

257

.RS 4

258

Select a UPS on a specific USB bus or group of busses\&. The argument is a regular expression that must match the bus name where the UPS is connected (e\&.g\&. bus="002", bus="00[2\-3]")\&.

259

.RE

260

.PP

261

\fBexplore\fR

262

.RS 4

263

With this option, the driver will connect to any device, including ones that are not yet supported\&. This must always be combined with the "vendorid" option\&. In this mode, the driver will not do anything useful except for printing debugging information (typically used with \-DD)\&.

264

.RE

265

.PP

266

\fBmaxreport\fR

267

.RS 4

268

With this option, the driver activates a tweak to workaround buggy firmware returning invalid HID report length\&. Some APC Back\-UPS units are known to have this bug\&.

269

.RE

270

.SH "INSTALLATION"

271

.sp

272

This driver is not built by default\&. You can build it by using "configure \-\-with\-usb=yes"\&. Note that it will also install other USB drivers\&.

273

.sp

274

You also need to install manually the legacy hotplug files (libhidups and libhid\&.usermap, generally in /etc/hotplug/usb/), or the udev file (nut\-usbups\&.rules, generally in /etc/udev/rules\&.d/) to address the permission settings problem\&. For more information, refer to the README file in nut/scripts/hotplug or nut/scripts/udev\&.

275

.sp

276

On Linux with MGE equipment, you will need at least a 2\&.4\&.25 or 2\&.6\&.2 kernel as well as libusb\-0\&.1\&.8 or later to disable hiddev support and avoid conflict\&.

277

.SH "IMPLEMENTATION"

278

.sp

279

The driver ignores the "port" value in \fBups\&.conf\fR\&. Unlike previous versions of this driver, it is now possible to control multiple UPS units simultaneously with this driver, provided they can be distinguished by setting some combination of the "vendor", "product", "serial", "vendorid", and "productid" options\&. For instance:

280

.sp

281

.if n \{\

282

.RS 4

283

.\}

284

.nf

285

[mge]

286

driver = usbhid\-ups

287

port = auto

288

vendorid = 0463

289

[tripplite]

290

driver = usbhid\-ups

291

port = auto

292

vendorid = 09ae

293

.fi

294

.if n \{\

295

.RE

296

.\}

297

.SH "KNOWN ISSUES AND BUGS"

298

.SS "Repetitive timeout and staleness"

299

.sp

300

Some models tends to be unresponsive with the default polling frequency\&. The result is that your system log will have lots of messages like:

301

.sp

302

.if n \{\

303

.RS 4

304

.\}

305

.nf

306

usb 2\-1: control timeout on ep0in

307

usb 2\-1: usbfs: USBDEVFS_CONTROL failed cmd usbhid\-ups rqt 128 rq 6 len 256

308

ret \-110

309

.fi

310

.if n \{\

311

.RE

312

.\}

313

.sp

314

In this case, simply modify the general parameter "pollinterval" to a higher value (like 10 for 10 seconds)\&. This should solve the issue\&.

315

.SS "Got EPERM: Operation not permitted upon driver startup"

316

.sp

317

You have forgotten to install the hotplug files, as explained in the INSTALLATION section above\&. Don\(cqt forget to restart hotplug so that it applies these changes\&.

318

.SS "Unattended shutdowns"

319

.sp

320

The hardware which was used for development of this driver is almost certainly different from what you have, and not all manufacturers follow the USB HID Power Device Class specifications to the letter\&. You don\(cqt want to find out that yours has issues here when a power failure hits your server room and you\(cqre not around to manually restart your servers\&.

321

.sp

322

If you rely on the UPS to shutdown your systems in case of mains failure and to restart them when the power returns, you \fBmust\fR test this\&. You can do so by running \fIupsmon \-c fsd\fR\&. With the mains present, this should bring your systems down and then cycle the power to restart them again\&. If you do the same without mains present, it should do the same, but in this case, the outputs shall remain off until mains power is applied again\&.

323

.SH "AUTHORS"

324

.sp

325

Originally sponsored by MGE UPS SYSTEMS\&. Now sponsored by Eaton http://opensource\&.eaton\&.com Arnaud Quette, Peter Selinger, Arjen de Korte

326

.SH "SEE ALSO"

327

.SS "The core driver"

328

.sp

329

\fBnutupsdrv\fR(8)

330

.SS "Internet resources"

331

.sp

332

The NUT (Network UPS Tools) home page: http://www\&.networkupstools\&.org/

Older »