├── .gitignore ├── .travis.yml ├── LICENSE ├── README.md ├── asn1.go ├── examples └── agent │ └── agent.go ├── gen_readme.sh ├── snmp.go └── snmp_test.go /.gitignore: -------------------------------------------------------------------------------- 1 | # Compiled Object files, Static and Dynamic libs (Shared Objects) 2 | *.o 3 | *.a 4 | *.so 5 | 6 | # Folders 7 | _obj 8 | _test 9 | 10 | # Architecture specific extensions/prefixes 11 | *.[568vq] 12 | [568vq].out 13 | 14 | *.cgo1.go 15 | *.cgo2.c 16 | _cgo_defun.c 17 | _cgo_gotypes.go 18 | _cgo_export.* 19 | 20 | _testmain.go 21 | 22 | *.exe 23 | *.test 24 | *.prof 25 | -------------------------------------------------------------------------------- /.travis.yml: -------------------------------------------------------------------------------- 1 | language: go 2 | 3 | go: 4 | - 1.5 5 | -------------------------------------------------------------------------------- /LICENSE: -------------------------------------------------------------------------------- 1 | The MIT License (MIT) 2 | 3 | Copyright (c) 2016 PromonLogicalis 4 | 5 | Permission is hereby granted, free of charge, to any person obtaining a copy 6 | of this software and associated documentation files (the "Software"), to deal 7 | in the Software without restriction, including without limitation the rights 8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 9 | copies of the Software, and to permit persons to whom the Software is 10 | furnished to do so, subject to the following conditions: 11 | 12 | The above copyright notice and this permission notice shall be included in all 13 | copies or substantial portions of the Software. 14 | 15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE 21 | SOFTWARE. 22 | -------------------------------------------------------------------------------- /README.md: -------------------------------------------------------------------------------- 1 | --- 2 | 3 | # WARNING 4 | 5 | ## This repo has been archived! 6 | 7 | NO further developement will be made in the foreseen future. 8 | 9 | --- 10 | 11 | 12 | 13 | [![Build Status](https://travis-ci.org/PromonLogicalis/snmp.svg?branch=master)](https://travis-ci.org/PromonLogicalis/snmp) [![Go Report Card](https://goreportcard.com/badge/github.com/PromonLogicalis/snmp)](https://goreportcard.com/report/github.com/PromonLogicalis/snmp) [![GoDoc](https://godoc.org/github.com/PromonLogicalis/snmp?status.svg)](https://godoc.org/github.com/PromonLogicalis/snmp) 14 | # snmp 15 | -- 16 | import "github.com/PromonLogicalis/snmp" 17 | 18 | Package snmp implements low-level support for SNMP with focus in SNMP agents. 19 | 20 | At the encoding level it uses the PromonLogicalis/asn1 to parse and serialize 21 | SNMP messages providing Go types for that. 22 | 23 | The package also provides transport-independent support for creating custom SNMP 24 | agents with small footprint. 25 | 26 | A example of a simple SNMP UDP agent: 27 | 28 | package main 29 | 30 | import ( 31 | "log" 32 | "net" 33 | "time" 34 | 35 | "github.com/PromonLogicalis/asn1" 36 | "github.com/PromonLogicalis/snmp" 37 | ) 38 | 39 | func main() { 40 | agent := snmp.NewAgent() 41 | 42 | // Set the read-only and read-write communities 43 | agent.SetCommunities("publ", "priv") 44 | 45 | // Register a read-only OID. 46 | since := time.Now() 47 | agent.AddRoManagedObject( 48 | // sysUpTime 49 | asn1.Oid{1, 3, 6, 1, 2, 1, 1, 3, 0}, 50 | func(oid asn1.Oid) (interface{}, error) { 51 | seconds := int(time.Now().Sub(since) / time.Second) 52 | return seconds, nil 53 | }) 54 | 55 | // Register a read-write OID. 56 | name := "example" 57 | agent.AddRwManagedObject( 58 | // sysName 59 | asn1.Oid{1, 3, 6, 1, 2, 1, 1, 5, 0}, 60 | func(oid asn1.Oid) (interface{}, error) { 61 | return name, nil 62 | }, 63 | func(oid asn1.Oid, value interface{}) error { 64 | strValue, ok := value.(string) 65 | if !ok { 66 | return snmp.VarErrorf(snmp.BadValue, "invalid type") 67 | } 68 | name = strValue 69 | return nil 70 | }) 71 | 72 | // Bind to an UDP port 73 | addr, err := net.ResolveUDPAddr("udp", ":161") 74 | if err != nil { 75 | log.Fatal(err) 76 | } 77 | conn, err := net.ListenUDP("udp", addr) 78 | if err != nil { 79 | log.Fatal(err) 80 | } 81 | 82 | // Serve requests 83 | for { 84 | buffer := make([]byte, 1024) 85 | n, source, err := conn.ReadFrom(buffer) 86 | if err != nil { 87 | log.Fatal(err) 88 | } 89 | 90 | buffer, err = agent.ProcessDatagram(buffer[:n]) 91 | if err != nil { 92 | log.Println(err) 93 | continue 94 | } 95 | 96 | _, err = conn.WriteTo(buffer, source) 97 | if err != nil { 98 | log.Fatal(err) 99 | } 100 | } 101 | } 102 | 103 | ## Usage 104 | 105 | ```go 106 | const ( 107 | NoError = 0 108 | TooBig = 1 109 | NoSuchName = 2 110 | BadValue = 3 111 | ReadOnly = 4 112 | GenErr = 5 113 | NoAccess = 6 114 | WrongType = 7 115 | WrongLength = 8 116 | WrongEncoding = 9 117 | WrongValue = 10 118 | NoCreation = 11 119 | InconsistentValue = 12 120 | ResourceUnavailable = 13 121 | CommitFailed = 14 122 | UndoFailed = 15 123 | AuthorizationError = 16 124 | NotWritable = 17 125 | InconsistentName = 18 126 | ) 127 | ``` 128 | SNMP error codes. 129 | 130 | #### func Asn1Context 131 | 132 | ```go 133 | func Asn1Context() *asn1.Context 134 | ``` 135 | Asn1Context returns a new allocated asn1.Context and registers all the choice 136 | types necessary for SNMPv1 and SNMPv2. 137 | 138 | #### type Agent 139 | 140 | ```go 141 | type Agent struct { 142 | } 143 | ``` 144 | 145 | Agent is a transport independent engine to process SNMP requests. 146 | 147 | #### func NewAgent 148 | 149 | ```go 150 | func NewAgent() *Agent 151 | ``` 152 | NewAgent create and initialize an agent. 153 | 154 | #### func (*Agent) AddRoManagedObject 155 | 156 | ```go 157 | func (a *Agent) AddRoManagedObject(oid asn1.Oid, getter Getter) error 158 | ``` 159 | AddRoManagedObject registers a read-only managed object. 160 | 161 | #### func (*Agent) AddRwManagedObject 162 | 163 | ```go 164 | func (a *Agent) AddRwManagedObject(oid asn1.Oid, getter Getter, 165 | setter Setter) error 166 | ``` 167 | AddRwManagedObject registers a read-write managed object. 168 | 169 | The inteface{} values returned by a Getter or received by a Setter must be of 170 | one of the following types: 171 | 172 | int 173 | string 174 | asn1.Null 175 | asn1.Oid 176 | snmp.Counter32 177 | snmp.Counter64 178 | snmp.IpAddress 179 | snmp.Opaque 180 | snmp.TimeTicks 181 | snmp.Unsigned32 182 | 183 | #### func (*Agent) ProcessDatagram 184 | 185 | ```go 186 | func (a *Agent) ProcessDatagram(requestBytes []byte) (responseBytes []byte, err error) 187 | ``` 188 | ProcessDatagram handles a binany SNMP message. 189 | 190 | #### func (*Agent) ProcessMessage 191 | 192 | ```go 193 | func (a *Agent) ProcessMessage(request *Message) (response *Message, err error) 194 | ``` 195 | ProcessMessage handles a SNMP Message. 196 | 197 | #### func (*Agent) SetCommunities 198 | 199 | ```go 200 | func (a *Agent) SetCommunities(public, private string) 201 | ``` 202 | SetCommunities defines the public and private communities. 203 | 204 | #### func (*Agent) SetLogger 205 | 206 | ```go 207 | func (a *Agent) SetLogger(logger *log.Logger) 208 | ``` 209 | SetLogger defines the logger used for internal messages. 210 | 211 | #### type BulkPdu 212 | 213 | ```go 214 | type BulkPdu struct { 215 | Identifier int 216 | NonRepeaters int 217 | MaxRepetitions int 218 | Variables []Variable 219 | } 220 | ``` 221 | 222 | BulkPdu is a generic type for other Protocol Data Units. 223 | 224 | #### type Counter32 225 | 226 | ```go 227 | type Counter32 uint32 228 | ``` 229 | 230 | Counter32 is a counter type. 231 | 232 | #### type Counter64 233 | 234 | ```go 235 | type Counter64 uint64 236 | ``` 237 | 238 | Counter64 is a counter type. 239 | 240 | #### type EndOfMibView 241 | 242 | ```go 243 | type EndOfMibView asn1.Null 244 | ``` 245 | 246 | EndOfMibView exception. 247 | 248 | #### func (EndOfMibView) String 249 | 250 | ```go 251 | func (e EndOfMibView) String() string 252 | ``` 253 | 254 | #### type GetBulkRequestPdu 255 | 256 | ```go 257 | type GetBulkRequestPdu BulkPdu 258 | ``` 259 | 260 | GetBulkRequestPdu is used for bulk requests. 261 | 262 | #### type GetNextRequestPdu 263 | 264 | ```go 265 | type GetNextRequestPdu Pdu 266 | ``` 267 | 268 | GetNextRequestPdu works similarly to GetRequestPdu, but it's returned the value 269 | for the next valid Oid. 270 | 271 | #### type GetRequestPdu 272 | 273 | ```go 274 | type GetRequestPdu Pdu 275 | ``` 276 | 277 | GetRequestPdu is used to request data. 278 | 279 | #### type GetResponsePdu 280 | 281 | ```go 282 | type GetResponsePdu Pdu 283 | ``` 284 | 285 | GetResponsePdu is used in responses to SNMP requests. 286 | 287 | #### type Getter 288 | 289 | ```go 290 | type Getter func(oid asn1.Oid) (interface{}, error) 291 | ``` 292 | 293 | Getter is a function called to return a managed object value. 294 | 295 | #### type IPAddress 296 | 297 | ```go 298 | type IPAddress [4]byte 299 | ``` 300 | 301 | IPAddress is a IPv4 address. 302 | 303 | #### func (IPAddress) String 304 | 305 | ```go 306 | func (ip IPAddress) String() string 307 | ``` 308 | String returns a representation of IPAddress in dot notation. 309 | 310 | #### type InformRequestPdu 311 | 312 | ```go 313 | type InformRequestPdu Pdu 314 | ``` 315 | 316 | InformRequestPdu is used for inform requests. 317 | 318 | #### type Message 319 | 320 | ```go 321 | type Message struct { 322 | Version int 323 | Community string 324 | Pdu interface{} `asn1:"choice:pdu"` 325 | } 326 | ``` 327 | 328 | Message is the top level element of the SNMP protocol. 329 | 330 | #### type NoSuchInstance 331 | 332 | ```go 333 | type NoSuchInstance asn1.Null 334 | ``` 335 | 336 | NoSuchInstance exception. 337 | 338 | #### func (NoSuchInstance) String 339 | 340 | ```go 341 | func (e NoSuchInstance) String() string 342 | ``` 343 | 344 | #### type NoSuchObject 345 | 346 | ```go 347 | type NoSuchObject asn1.Null 348 | ``` 349 | 350 | NoSuchObject exception. 351 | 352 | #### func (NoSuchObject) String 353 | 354 | ```go 355 | func (e NoSuchObject) String() string 356 | ``` 357 | 358 | #### type Opaque 359 | 360 | ```go 361 | type Opaque []byte 362 | ``` 363 | 364 | Opaque is a type for blobs. 365 | 366 | #### type Pdu 367 | 368 | ```go 369 | type Pdu struct { 370 | Identifier int 371 | ErrorStatus int 372 | ErrorIndex int 373 | Variables []Variable 374 | } 375 | ``` 376 | 377 | Pdu is a generic type for other Protocol Data Units. 378 | 379 | #### type SetRequestPdu 380 | 381 | ```go 382 | type SetRequestPdu Pdu 383 | ``` 384 | 385 | SetRequestPdu is used to request data to be updated. 386 | 387 | #### type Setter 388 | 389 | ```go 390 | type Setter func(oid asn1.Oid, value interface{}) error 391 | ``` 392 | 393 | Setter is a function called to set a managed object value. 394 | 395 | #### type TimeTicks 396 | 397 | ```go 398 | type TimeTicks uint32 399 | ``` 400 | 401 | TimeTicks is a type for time. 402 | 403 | #### type Unsigned32 404 | 405 | ```go 406 | type Unsigned32 uint32 407 | ``` 408 | 409 | Unsigned32 is an integer type. 410 | 411 | #### type V1TrapPdu 412 | 413 | ```go 414 | type V1TrapPdu struct { 415 | Enterprise asn1.Oid 416 | AgentAddr IPAddress 417 | GenericTrap int 418 | SpecificTrap int 419 | Timestamp TimeTicks 420 | Variables []Variable 421 | } 422 | ``` 423 | 424 | V1TrapPdu is used when sending a trap in SNMPv1. 425 | 426 | #### type V2TrapPdu 427 | 428 | ```go 429 | type V2TrapPdu Pdu 430 | ``` 431 | 432 | V2TrapPdu is used when sending a trap in SNMPv2. 433 | 434 | #### type VarError 435 | 436 | ```go 437 | type VarError struct { 438 | Status int 439 | Message string 440 | } 441 | ``` 442 | 443 | VarError is an error type that can be returned by a Getter or a Setter. When 444 | VarError is returned, it Status is used in the SNMP response. 445 | 446 | #### func VarErrorf 447 | 448 | ```go 449 | func VarErrorf(status int, format string, values ...interface{}) VarError 450 | ``` 451 | VarErrorf creates a new Error with a formatted message. 452 | 453 | #### func (VarError) Error 454 | 455 | ```go 456 | func (e VarError) Error() string 457 | ``` 458 | 459 | #### type Variable 460 | 461 | ```go 462 | type Variable struct { 463 | Name asn1.Oid 464 | Value interface{} `asn1:"choice:val"` 465 | } 466 | ``` 467 | 468 | Variable represents an entry of the variable bindings 469 | -------------------------------------------------------------------------------- /asn1.go: -------------------------------------------------------------------------------- 1 | package snmp 2 | 3 | import ( 4 | "fmt" 5 | "reflect" 6 | 7 | "github.com/PromonLogicalis/asn1" 8 | ) 9 | 10 | // SNMP error codes. 11 | const ( 12 | NoError = 0 13 | TooBig = 1 14 | NoSuchName = 2 15 | BadValue = 3 16 | ReadOnly = 4 17 | GenErr = 5 18 | NoAccess = 6 19 | WrongType = 7 20 | WrongLength = 8 21 | WrongEncoding = 9 22 | WrongValue = 10 23 | NoCreation = 11 24 | InconsistentValue = 12 25 | ResourceUnavailable = 13 26 | CommitFailed = 14 27 | UndoFailed = 15 28 | AuthorizationError = 16 29 | NotWritable = 17 30 | InconsistentName = 18 31 | ) 32 | 33 | // Message is the top level element of the SNMP protocol. 34 | type Message struct { 35 | Version int 36 | Community string 37 | Pdu interface{} `asn1:"choice:pdu"` 38 | } 39 | 40 | // Pdu is a generic type for other Protocol Data Units. 41 | type Pdu struct { 42 | Identifier int 43 | ErrorStatus int 44 | ErrorIndex int 45 | Variables []Variable 46 | } 47 | 48 | // BulkPdu is a generic type for other Protocol Data Units. 49 | type BulkPdu struct { 50 | Identifier int 51 | NonRepeaters int 52 | MaxRepetitions int 53 | Variables []Variable 54 | } 55 | 56 | // GetRequestPdu is used to request data. 57 | type GetRequestPdu Pdu 58 | 59 | // GetNextRequestPdu works similarly to GetRequestPdu, but it's returned the 60 | // value for the next valid Oid. 61 | type GetNextRequestPdu Pdu 62 | 63 | // GetResponsePdu is used in responses to SNMP requests. 64 | type GetResponsePdu Pdu 65 | 66 | // SetRequestPdu is used to request data to be updated. 67 | type SetRequestPdu Pdu 68 | 69 | // V1TrapPdu is used when sending a trap in SNMPv1. 70 | type V1TrapPdu struct { 71 | Enterprise asn1.Oid 72 | AgentAddr IPAddress 73 | GenericTrap int 74 | SpecificTrap int 75 | Timestamp TimeTicks 76 | Variables []Variable 77 | } 78 | 79 | // GetBulkRequestPdu is used for bulk requests. 80 | type GetBulkRequestPdu BulkPdu 81 | 82 | // InformRequestPdu is used for inform requests. 83 | type InformRequestPdu Pdu 84 | 85 | // V2TrapPdu is used when sending a trap in SNMPv2. 86 | type V2TrapPdu Pdu 87 | 88 | // Variable represents an entry of the variable bindings 89 | type Variable struct { 90 | Name asn1.Oid 91 | Value interface{} `asn1:"choice:val"` 92 | } 93 | 94 | // Types available for Variable.Value 95 | 96 | // IPAddress is a IPv4 address. 97 | type IPAddress [4]byte 98 | 99 | // String returns a representation of IPAddress in dot notation. 100 | func (ip IPAddress) String() string { 101 | return fmt.Sprintf("%d.%d.%d.%d", ip[0], ip[1], ip[2], ip[3]) 102 | } 103 | 104 | // Counter32 is a counter type. 105 | type Counter32 uint32 106 | 107 | // Unsigned32 is an integer type. 108 | type Unsigned32 uint32 109 | 110 | // TimeTicks is a type for time. 111 | type TimeTicks uint32 112 | 113 | // Opaque is a type for blobs. 114 | type Opaque []byte 115 | 116 | // Counter64 is a counter type. 117 | type Counter64 uint64 118 | 119 | // Exceptions available for Variable.Value 120 | 121 | // NoSuchObject exception. 122 | type NoSuchObject asn1.Null 123 | 124 | func (e NoSuchObject) String() string { return "NoSuchObject" } 125 | 126 | // NoSuchInstance exception. 127 | type NoSuchInstance asn1.Null 128 | 129 | func (e NoSuchInstance) String() string { return "NoSuchInstance" } 130 | 131 | // EndOfMibView exception. 132 | type EndOfMibView asn1.Null 133 | 134 | func (e EndOfMibView) String() string { return "EndOfMibView" } 135 | 136 | // Asn1Context returns a new allocated asn1.Context and registers all the 137 | // choice types necessary for SNMPv1 and SNMPv2. 138 | func Asn1Context() *asn1.Context { 139 | ctx := asn1.NewContext() 140 | ctx.AddChoice("pdu", []asn1.Choice{ 141 | { 142 | Type: reflect.TypeOf(GetRequestPdu{}), 143 | Options: "tag:0", 144 | }, 145 | { 146 | Type: reflect.TypeOf(GetNextRequestPdu{}), 147 | Options: "tag:1", 148 | }, 149 | { 150 | Type: reflect.TypeOf(GetResponsePdu{}), 151 | Options: "tag:2", 152 | }, 153 | { 154 | Type: reflect.TypeOf(SetRequestPdu{}), 155 | Options: "tag:3", 156 | }, 157 | { 158 | Type: reflect.TypeOf(V1TrapPdu{}), 159 | Options: "tag:4", 160 | }, 161 | { 162 | Type: reflect.TypeOf(GetBulkRequestPdu{}), 163 | Options: "tag:5", 164 | }, 165 | { 166 | Type: reflect.TypeOf(InformRequestPdu{}), 167 | Options: "tag:6", 168 | }, 169 | { 170 | Type: reflect.TypeOf(V2TrapPdu{}), 171 | Options: "tag:7", 172 | }, 173 | }) 174 | ctx.AddChoice("val", []asn1.Choice{ 175 | // Simple syntax 176 | { 177 | Type: reflect.TypeOf(asn1.Null{}), 178 | }, 179 | { 180 | Type: reflect.TypeOf(int(0)), 181 | }, 182 | { 183 | Type: reflect.TypeOf(""), 184 | }, 185 | { 186 | Type: reflect.TypeOf(asn1.Oid{}), 187 | }, 188 | // Application wide 189 | { 190 | Type: reflect.TypeOf(IPAddress{}), 191 | Options: "application,tag:0", 192 | }, 193 | { 194 | Type: reflect.TypeOf(Counter32(0)), 195 | Options: "application,tag:1", 196 | }, 197 | { 198 | Type: reflect.TypeOf(Unsigned32(0)), 199 | Options: "application,tag:2", 200 | }, 201 | { 202 | Type: reflect.TypeOf(TimeTicks(0)), 203 | Options: "application,tag:3", 204 | }, 205 | { 206 | Type: reflect.TypeOf(Opaque("")), 207 | Options: "application,tag:4", 208 | }, 209 | // [APPLICATION 5] does not exist. 210 | { 211 | Type: reflect.TypeOf(Counter64(0)), 212 | Options: "application,tag:6", 213 | }, 214 | // Exceptions 215 | { 216 | Type: reflect.TypeOf(NoSuchObject{}), 217 | Options: "tag:0", 218 | }, 219 | { 220 | Type: reflect.TypeOf(NoSuchInstance{}), 221 | Options: "tag:1", 222 | }, 223 | { 224 | Type: reflect.TypeOf(EndOfMibView{}), 225 | Options: "tag:2", 226 | }, 227 | }) 228 | return ctx 229 | } 230 | -------------------------------------------------------------------------------- /examples/agent/agent.go: -------------------------------------------------------------------------------- 1 | package main 2 | 3 | import ( 4 | "log" 5 | "net" 6 | "time" 7 | 8 | "github.com/PromonLogicalis/asn1" 9 | "github.com/PromonLogicalis/snmp" 10 | ) 11 | 12 | func main() { 13 | agent := snmp.NewAgent() 14 | 15 | // Set the read-only and read-write communities 16 | agent.SetCommunities("publ", "priv") 17 | 18 | // Register a read-only OID. 19 | since := time.Now() 20 | agent.AddRoManagedObject( 21 | // sysUpTime 22 | asn1.Oid{1, 3, 6, 1, 2, 1, 1, 3, 0}, 23 | func(oid asn1.Oid) (interface{}, error) { 24 | seconds := int(time.Now().Sub(since) / time.Second) 25 | return seconds, nil 26 | }) 27 | 28 | // Register a read-write OID. 29 | name := "example" 30 | agent.AddRwManagedObject( 31 | // sysName 32 | asn1.Oid{1, 3, 6, 1, 2, 1, 1, 5, 0}, 33 | func(oid asn1.Oid) (interface{}, error) { 34 | return name, nil 35 | }, 36 | func(oid asn1.Oid, value interface{}) error { 37 | strValue, ok := value.(string) 38 | if !ok { 39 | return snmp.VarErrorf(snmp.BadValue, "invalid type") 40 | } 41 | name = strValue 42 | return nil 43 | }) 44 | 45 | // Bind to an UDP port 46 | addr, err := net.ResolveUDPAddr("udp", ":161") 47 | if err != nil { 48 | log.Fatal(err) 49 | } 50 | conn, err := net.ListenUDP("udp", addr) 51 | if err != nil { 52 | log.Fatal(err) 53 | } 54 | 55 | // Serve requests 56 | for { 57 | buffer := make([]byte, 1024) 58 | n, source, err := conn.ReadFrom(buffer) 59 | if err != nil { 60 | log.Fatal(err) 61 | } 62 | 63 | buffer, err = agent.ProcessDatagram(buffer[:n]) 64 | if err != nil { 65 | log.Println(err) 66 | continue 67 | } 68 | 69 | _, err = conn.WriteTo(buffer, source) 70 | if err != nil { 71 | log.Fatal(err) 72 | } 73 | } 74 | } 75 | -------------------------------------------------------------------------------- /gen_readme.sh: -------------------------------------------------------------------------------- 1 | #!/bin/bash 2 | 3 | # Add Travis badge: 4 | cat > ./README.md << 'EOF' 5 | [![Build Status](https://travis-ci.org/PromonLogicalis/snmp.svg?branch=master)](https://travis-ci.org/PromonLogicalis/snmp) [![Go Report Card](https://goreportcard.com/badge/github.com/PromonLogicalis/snmp)](https://goreportcard.com/report/github.com/PromonLogicalis/snmp) [![GoDoc](https://godoc.org/github.com/PromonLogicalis/snmp?status.svg)](https://godoc.org/github.com/PromonLogicalis/snmp) 6 | EOF 7 | 8 | # Add Go doc 9 | godocdown ./ >> ./README.md 10 | -------------------------------------------------------------------------------- /snmp.go: -------------------------------------------------------------------------------- 1 | // Package snmp implements low-level support for SNMP with focus in SNMP 2 | // agents. 3 | // 4 | // At the encoding level it uses the PromonLogicalis/asn1 to parse and 5 | // serialize SNMP messages providing Go types for that. 6 | // 7 | // The package also provides transport-independent support for creating custom 8 | // SNMP agents with small footprint. 9 | // 10 | // A example of a simple SNMP UDP agent: 11 | // 12 | // package main 13 | // 14 | // import ( 15 | // "log" 16 | // "net" 17 | // "time" 18 | // 19 | // "github.com/PromonLogicalis/asn1" 20 | // "github.com/PromonLogicalis/snmp" 21 | // ) 22 | // 23 | // func main() { 24 | // agent := snmp.NewAgent() 25 | // 26 | // // Set the read-only and read-write communities 27 | // agent.SetCommunities("publ", "priv") 28 | // 29 | // // Register a read-only OID. 30 | // since := time.Now() 31 | // agent.AddRoManagedObject( 32 | // // sysUpTime 33 | // asn1.Oid{1, 3, 6, 1, 2, 1, 1, 3, 0}, 34 | // func(oid asn1.Oid) (interface{}, error) { 35 | // seconds := int(time.Now().Sub(since) / time.Second) 36 | // return seconds, nil 37 | // }) 38 | // 39 | // // Register a read-write OID. 40 | // name := "example" 41 | // agent.AddRwManagedObject( 42 | // // sysName 43 | // asn1.Oid{1, 3, 6, 1, 2, 1, 1, 5, 0}, 44 | // func(oid asn1.Oid) (interface{}, error) { 45 | // return name, nil 46 | // }, 47 | // func(oid asn1.Oid, value interface{}) error { 48 | // strValue, ok := value.(string) 49 | // if !ok { 50 | // return snmp.VarErrorf(snmp.BadValue, "invalid type") 51 | // } 52 | // name = strValue 53 | // return nil 54 | // }) 55 | // 56 | // // Bind to an UDP port 57 | // addr, err := net.ResolveUDPAddr("udp", ":161") 58 | // if err != nil { 59 | // log.Fatal(err) 60 | // } 61 | // conn, err := net.ListenUDP("udp", addr) 62 | // if err != nil { 63 | // log.Fatal(err) 64 | // } 65 | // 66 | // // Serve requests 67 | // for { 68 | // buffer := make([]byte, 1024) 69 | // n, source, err := conn.ReadFrom(buffer) 70 | // if err != nil { 71 | // log.Fatal(err) 72 | // } 73 | // 74 | // buffer, err = agent.ProcessDatagram(buffer[:n]) 75 | // if err != nil { 76 | // log.Println(err) 77 | // continue 78 | // } 79 | // 80 | // _, err = conn.WriteTo(buffer, source) 81 | // if err != nil { 82 | // log.Fatal(err) 83 | // } 84 | // } 85 | // } 86 | // 87 | package snmp 88 | 89 | // TODO Support for traps 90 | // TODO More flexible ACL and authentication mechanism. 91 | // TODO Use the origin to process ACLs and authentication. 92 | // TODO Support for SNMPv2. 93 | 94 | import ( 95 | "fmt" 96 | "io/ioutil" 97 | "log" 98 | "reflect" 99 | "sort" 100 | 101 | "github.com/PromonLogicalis/asn1" 102 | ) 103 | 104 | // Getter is a function called to return a managed object value. 105 | type Getter func(oid asn1.Oid) (interface{}, error) 106 | 107 | // Setter is a function called to set a managed object value. 108 | type Setter func(oid asn1.Oid, value interface{}) error 109 | 110 | // Agent is a transport independent engine to process SNMP requests. 111 | type Agent struct { 112 | log *log.Logger 113 | ctx *asn1.Context 114 | handlers []managedObject 115 | public string 116 | private string 117 | } 118 | 119 | // NewAgent create and initialize an agent. 120 | func NewAgent() *Agent { 121 | a := &Agent{ctx: Asn1Context()} 122 | a.SetLogger(nil) 123 | a.SetCommunities("public", "private") 124 | return a 125 | } 126 | 127 | // SetLogger defines the logger used for internal messages. 128 | func (a *Agent) SetLogger(logger *log.Logger) { 129 | if logger == nil { 130 | logger = log.New(ioutil.Discard, "", 0) 131 | } 132 | a.log = logger 133 | a.ctx.SetLogger(logger) 134 | } 135 | 136 | // SetCommunities defines the public and private communities. 137 | func (a *Agent) SetCommunities(public, private string) { 138 | a.public, a.private = public, private 139 | } 140 | 141 | // checkCommunity handles "authentication" and acls 142 | func (a *Agent) checkCommunity(community string) (rw bool, err error) { 143 | 144 | // Access check. Right now only read-only community is implemented 145 | if community != a.public && community != a.private { 146 | // The agent should ignore invalid communities 147 | err = fmt.Errorf("invalid community \"%s\"", community) 148 | return 149 | } 150 | 151 | // Super complex ACLs 152 | if community == a.private { 153 | rw = true 154 | } 155 | return 156 | } 157 | 158 | // AddRoManagedObject registers a read-only managed object. 159 | func (a *Agent) AddRoManagedObject(oid asn1.Oid, getter Getter) error { 160 | return a.AddRwManagedObject(oid, getter, nil) 161 | } 162 | 163 | // AddRwManagedObject registers a read-write managed object. 164 | // 165 | // The inteface{} values returned by a Getter or received by a Setter must be 166 | // of one of the following types: 167 | // 168 | // int 169 | // string 170 | // asn1.Null 171 | // asn1.Oid 172 | // snmp.Counter32 173 | // snmp.Counter64 174 | // snmp.IpAddress 175 | // snmp.Opaque 176 | // snmp.TimeTicks 177 | // snmp.Unsigned32 178 | // 179 | func (a *Agent) AddRwManagedObject(oid asn1.Oid, getter Getter, 180 | setter Setter) error { 181 | 182 | if getter == nil { 183 | return fmt.Errorf("a managed object should have at least a getter") 184 | } 185 | if setter == nil { 186 | setter = func(oid asn1.Oid, value interface{}) error { 187 | return VarErrorf(NotWritable, "OID %s is not writable", oid) 188 | } 189 | } 190 | if a.getManagedObject(oid, false) != nil { 191 | return fmt.Errorf("OID %d is already registered", oid) 192 | } 193 | h := managedObject{oid, nil, getter, setter} 194 | a.handlers = append(a.handlers, h) 195 | sort.Sort(sortableManagedObjects(a.handlers)) 196 | return nil 197 | } 198 | 199 | // managedObject represents a registered managed object. 200 | type managedObject struct { 201 | oid asn1.Oid 202 | // TODO Add type check inside the agent processing. 203 | typ reflect.Type 204 | get Getter 205 | set Setter 206 | } 207 | 208 | // sortableManagedObjects is a helper type to sort managed objects slices. 209 | type sortableManagedObjects []managedObject 210 | 211 | func (h sortableManagedObjects) Len() int { return len(h) } 212 | func (h sortableManagedObjects) Swap(i, j int) { h[i], h[j] = h[j], h[i] } 213 | func (h sortableManagedObjects) Less(i, j int) bool { 214 | return h[i].oid.Cmp(h[j].oid) < 0 215 | } 216 | 217 | // getManagedObject returns the exact managed object for the given OID when 218 | // next=false or the next object when next=true. 219 | func (a *Agent) getManagedObject(oid asn1.Oid, next bool) *managedObject { 220 | for _, h := range a.handlers { 221 | cmp := oid.Cmp(h.oid) 222 | if (!next && cmp == 0) || (next && cmp < 0) { 223 | return &h 224 | } 225 | if !next && cmp < 0 { 226 | break 227 | } 228 | } 229 | return nil 230 | } 231 | 232 | // ProcessMessage handles a SNMP Message. 233 | func (a *Agent) ProcessMessage(request *Message) (response *Message, err error) { 234 | // SNMPv1 only for now 235 | if request.Version != 0 { 236 | // Discard SNMPv2 messages 237 | err = fmt.Errorf("invalid SNMP version %d", request.Version) 238 | return 239 | } 240 | 241 | rw, err := a.checkCommunity(request.Community) 242 | if err != nil { 243 | return 244 | } 245 | 246 | // Dispatch each type of PDU 247 | a.log.Printf("request: %#v\n", request) 248 | var res GetResponsePdu 249 | switch pdu := request.Pdu.(type) { 250 | case GetRequestPdu: 251 | res = a.processPdu(Pdu(pdu), false, false) 252 | case GetNextRequestPdu: 253 | res = a.processPdu(Pdu(pdu), true, false) 254 | case SetRequestPdu: 255 | if rw { 256 | res = a.processPdu(Pdu(pdu), false, true) 257 | } else { 258 | res = GetResponsePdu(pdu) 259 | res.ErrorIndex = 1 260 | res.ErrorStatus = NoSuchName 261 | } 262 | default: 263 | // SNMPv2 PDUs are ignored 264 | err = fmt.Errorf("PDU not supported: %T", request.Pdu) 265 | return 266 | } 267 | 268 | // Copy request 269 | copy := *request 270 | response = © 271 | 272 | // Set response 273 | response.Pdu = res 274 | a.log.Printf("response: %#v\n", response) 275 | return 276 | } 277 | 278 | // ProcessDatagram handles a binany SNMP message. 279 | func (a *Agent) ProcessDatagram(requestBytes []byte) (responseBytes []byte, err error) { 280 | // Decode message. Invalid messages are discarded 281 | request := Message{} 282 | ctx := Asn1Context() 283 | remaining, err := ctx.Decode(requestBytes, &request) 284 | if err != nil { 285 | return 286 | } 287 | if len(remaining) > 0 { 288 | err = fmt.Errorf("%d remaining bytes.\n", len(remaining)) 289 | return 290 | } 291 | 292 | // Process message 293 | response, err := a.ProcessMessage(&request) 294 | if err != nil { 295 | return 296 | } 297 | 298 | responseBytes, err = ctx.Encode(*response) 299 | return 300 | } 301 | 302 | // processPdu handles SNMPv1 requests with exception of SnmpV1TrapPdu. 303 | func (a *Agent) processPdu(pdu Pdu, next bool, set bool) GetResponsePdu { 304 | 305 | // Keep returned values in a separated slice for a Get request 306 | var variables []Variable 307 | 308 | var err error 309 | res := GetResponsePdu(pdu) 310 | for i, v := range pdu.Variables { 311 | a.log.Printf("oid: %s\n", v.Name) 312 | // Retrieve the managed object 313 | h := a.getManagedObject(v.Name, next) 314 | if h == nil { 315 | res.ErrorIndex = i + 1 316 | res.ErrorStatus = NoSuchName 317 | return res 318 | } 319 | // Set or get the value 320 | var value interface{} 321 | if set { 322 | err = h.set(h.oid, v.Value) 323 | } else { 324 | value, err = h.get(h.oid) 325 | } 326 | if err != nil { 327 | res.ErrorIndex = i + 1 328 | if e, ok := err.(VarError); ok { 329 | res.ErrorStatus = e.Status 330 | } else { 331 | res.ErrorStatus = GenErr 332 | } 333 | return res 334 | } 335 | // Values returned by a Get are kept in a separated list. If an error 336 | // occurs the original list of variables should be returned. 337 | if !set { 338 | variables = append(variables, Variable{h.oid, value}) 339 | } 340 | } 341 | if !set { 342 | // Update all values, since all variables were processed without error: 343 | res.Variables = variables 344 | } 345 | return res 346 | } 347 | 348 | // VarError is an error type that can be returned by a Getter or a Setter. When 349 | // VarError is returned, it Status is used in the SNMP response. 350 | type VarError struct { 351 | Status int 352 | Message string 353 | } 354 | 355 | var _ error = VarError{} 356 | 357 | func (e VarError) Error() string { 358 | return fmt.Sprintf("%s (status: %d)", e.Message, e.Status) 359 | } 360 | 361 | // VarErrorf creates a new Error with a formatted message. 362 | func VarErrorf(status int, format string, values ...interface{}) VarError { 363 | return VarError{ 364 | Status: status, 365 | Message: fmt.Sprintf(format, values...), 366 | } 367 | } 368 | -------------------------------------------------------------------------------- /snmp_test.go: -------------------------------------------------------------------------------- 1 | package snmp 2 | 3 | import ( 4 | "fmt" 5 | "testing" 6 | 7 | "github.com/PromonLogicalis/asn1" 8 | ) 9 | 10 | // TODO test GetNextRequestPdu and SetRequestPdu 11 | 12 | func getResquestForTest() []byte { 13 | // Version = 1 14 | // Pdu = GetRequest 15 | // Oid = .iso.org.dod.internet.mgmt.mib-2.system.sysUpTime.sysUpTimeInstance.0 16 | // Community = "publ" 17 | data := []byte{ 18 | 0x30, 0x27, 0x02, 0x01, 0x00, 0x04, 0x04, 0x70, 0x75, 0x62, 0x6c, 0xa0, 19 | 0x1c, 0x02, 0x04, 0x74, 0x25, 0x43, 0x6c, 0x02, 0x01, 0x00, 0x02, 0x01, 20 | 0x00, 0x30, 0x0e, 0x30, 0x0c, 0x06, 0x08, 0x2b, 0x06, 0x01, 0x02, 0x01, 21 | 0x01, 0x03, 0x00, 0x05, 0x00, 22 | } 23 | return data 24 | } 25 | 26 | func TestGet(t *testing.T) { 27 | 28 | uptimeOid := asn1.Oid{1, 3, 6, 1, 2, 1, 1, 3, 0} 29 | data := getResquestForTest() 30 | 31 | uptime := 123 32 | agent := NewAgent() 33 | agent.SetCommunities("publ", "priv") 34 | agent.AddRoManagedObject(uptimeOid, 35 | func(oid asn1.Oid) (interface{}, error) { 36 | return uptime, nil 37 | }) 38 | data, err := agent.ProcessDatagram(data) 39 | if err != nil { 40 | t.Fatal(err) 41 | } 42 | 43 | message := Message{} 44 | _, err = Asn1Context().Decode(data, &message) 45 | if err != nil { 46 | t.Fatal(err) 47 | } 48 | response, ok := message.Pdu.(GetResponsePdu) 49 | if !ok { 50 | t.Fatalf("Invalid PDU type: %T\n", message.Pdu) 51 | } 52 | if response.ErrorStatus != 0 { 53 | t.Fatalf("Response contains an error: %d\n", response.ErrorStatus) 54 | } 55 | if len(response.Variables) < 1 { 56 | t.Fatalf("Response is missing variables.\n") 57 | } 58 | if response.Variables[0].Value != uptime { 59 | t.Fatalf("Wrong response value %v\n", response.Variables[0].Value) 60 | } 61 | } 62 | 63 | func TestNoSuchName(t *testing.T) { 64 | 65 | uptimeOid := asn1.Oid{1, 3, 6, 1, 2, 1, 1, 3} 66 | data := getResquestForTest() 67 | 68 | agent := NewAgent() 69 | agent.SetCommunities("publ", "priv") 70 | agent.AddRoManagedObject(uptimeOid, 71 | func(oid asn1.Oid) (interface{}, error) { 72 | return 0, nil 73 | }) 74 | data, err := agent.ProcessDatagram(data) 75 | if err != nil { 76 | t.Fatal(err) 77 | } 78 | 79 | message := Message{} 80 | _, err = Asn1Context().Decode(data, &message) 81 | if err != nil { 82 | t.Fatal(err) 83 | } 84 | response, ok := message.Pdu.(GetResponsePdu) 85 | if !ok { 86 | t.Fatalf("Invalid PDU type: %T\n", message.Pdu) 87 | } 88 | if response.ErrorStatus != NoSuchName { 89 | t.Fatalf( 90 | "Response should contain error %d. Got %d instead.\n", 91 | NoSuchName, response.ErrorStatus) 92 | } 93 | } 94 | 95 | func TestError(t *testing.T) { 96 | 97 | uptimeOid := asn1.Oid{1, 3, 6, 1, 2, 1, 1, 3, 0} 98 | data := getResquestForTest() 99 | 100 | agent := NewAgent() 101 | agent.SetCommunities("publ", "priv") 102 | agent.AddRoManagedObject(uptimeOid, 103 | func(oid asn1.Oid) (interface{}, error) { 104 | return nil, VarErrorf(BadValue, "error") 105 | }) 106 | data, err := agent.ProcessDatagram(data) 107 | if err != nil { 108 | t.Fatal(err) 109 | } 110 | 111 | message := Message{} 112 | _, err = Asn1Context().Decode(data, &message) 113 | if err != nil { 114 | t.Fatal(err) 115 | } 116 | response, ok := message.Pdu.(GetResponsePdu) 117 | if !ok { 118 | t.Fatalf("Invalid PDU type: %T\n", message.Pdu) 119 | } 120 | if response.ErrorStatus != BadValue { 121 | t.Fatalf( 122 | "Response should contain error %d. Got %d instead.\n", 123 | BadValue, response.ErrorStatus) 124 | } 125 | } 126 | 127 | func TestCommunity(t *testing.T) { 128 | 129 | uptimeOid := asn1.Oid{1, 3, 6, 1, 2, 1, 1, 3, 0} 130 | data := getResquestForTest() 131 | 132 | uptime := 123 133 | agent := NewAgent() 134 | agent.SetCommunities("secret", "secret") 135 | agent.AddRoManagedObject(uptimeOid, 136 | func(oid asn1.Oid) (interface{}, error) { 137 | return uptime, nil 138 | }) 139 | data, err := agent.ProcessDatagram(data) 140 | if err == nil { 141 | t.Fatal("Request with wrong Community should fail.") 142 | } 143 | } 144 | 145 | func TestString(t *testing.T) { 146 | objs := []fmt.Stringer{ 147 | IPAddress{192, 168, 0, 1}, 148 | NoSuchObject{}, 149 | NoSuchInstance{}, 150 | EndOfMibView{}, 151 | } 152 | for _, obj := range objs { 153 | if len(obj.String()) == 0 { 154 | t.Fatalf("Invalid string: %v\n", obj) 155 | } 156 | } 157 | 158 | } 159 | --------------------------------------------------------------------------------